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PROGRAMMING USER TASKS 


Introduction 


A program is a collectioh of machine instructions which directs the 
activities of a computer. Under TAXO, on activation of o program is 
called a task, There may be several activations of the some program 
at a given time but each activation is a different task, For example, 
the System Command Interpreter (SCI) is a progrom and each station 
may have, as a task, a unique activation of the SCI progrom, A pro- 
gram "becomes" a task when TAXO assigns a runtime ID, A program may 
become several identical tasks if TAXO assigns several runtime IDs, 
To save memory, TAXO uses mapping to allow tasks to share common pro- 
cedure or data segments. 


1.2 Program Mapping 


The TA 1630 eaiutes hardware has a 20-bit memory address bus and can 
address 1024K words of memory. The logical address space available to 
a task is limited, by o 15-bit word address, to 32K words. This dif- 
ference is resolved by mapping the task's logical address space into 
the computer's physical address space. As shown in figure 1-1, the 
mapping hardware can map 1, 2, or 3 segments of logical address space 
into 1, 2, or 3.segments of physical address space, 


The segments in physical address space need not be contiguous. Since 
TAXO maintains separate mapping parameters for each task, each task 
may consist of one, two, or three segments with a total extent of 

32K words. Further, several tasks may share one or two segments. One 
segment, however, is unique to eoch instance of a program. This unique 
segment is called the task segment. The shareable segments of a task 
are called procedure segments. Figure 1-2 illustrates two tasks sharing 
two segments of memory, The two tasks could be instances of the same 
program, For example, both tasks might be instances of the SCI program 
executing ot different stations. 


The instructions which control mapping ore reserved for system use 
(use of these instructions by nonprivileged user tasks causes fatal 
errors). TAXO memory management controls mapping so that the mapping 
function is transparent to user tasks, 
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Program mentation 
Mapping allows users to segment programs as: 


“1, A single program segment, including both data base and executable 


code, When installed on a progrom file, this segment is called a 
task segment and each instance of the program in execution is 
' called a task, 


2. Two separately loadable program segments consisting of a procedure 
segment and a task segment. 


3, Three separate program segments, consisting of two procedure seg- 
ments and o task segment. 


4, Programs with fewer than three segments may access System Common, 
which is allocated to the calling task by the Get Common supervisor 
call. 

Since TAXO manages memory in 32-byte blocks, the following boundary 

rules apply for programs consisting of two or three separate segments: 


1, The first procedure segment (if any) begins at address 0 in the lo- 
gical address space seen by the executing program. 


2. The second procedure segment (if any) begins on the first 32 byte 
boundary immediately following the first procedure in the logical 
address space seen by the executing program. 


3. The task segment begins on the 32 byte boundary immediately follow- 
ing the last procedure in the logical address space seen by the 
executing program, 


These memory boundary requirements are supported by the Link Editor, as 
defined in the Link Editor Reference Manual, 
* 


Transfer Vector 


TAXO transfers control to a task via a transfer vector in the task 
segment, The first three words of the task segment must consist of the 
following vector: 


First Word: Initial Workspace address (WP). 
Second Word: Initial procedure entry point address (PC). 
Third Word: End action entry point address. 


For exemple: IDT ‘TASK' 
REF PROCI, ERPROC 


DATA WSPACE 
DATA PROC] 
DATA ERPROC 
WSPACE BSS 32 WORKSPACE 
e e 
* Task Data 
bas e e 
* e e 
END 
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If the end action entry point address is less than or equal to 15, 
TAXO terminates the task when a fatal error is detected. If the 
address is greater than Fi, control is transferred to the specified 
address, Whenever a task fatal error occurs, if no end action routine 
exists or when the end action routine executes an End Task supervisor 
call (4), TAXO releases resources from the task and takes it out of 
execution, High-level language processors generate transfer vectors 
automatically, 


Sharing Procedure Segments 

Procedure segments generally contain executable code while the task 
segment contains local data, Tasks may share procedures which ore re- 
entrant. Reentrant procedures are read only and manipulate data only 
in task segments, Tasks sharing procedures must be copies of each 
other to the extent that data structures referenced by a procedure 
must be at the same relative locations in each task. Nothing, however, 
prohibits having executable code in a task segment and data in a pro- 
cedure segment, Such tasks must adopt conventions for selecting a task 
to modify common data in order to prevent conflicts. 


Memory Configurations and Procedural Steps 


Figure 1-3 illustrates the possible memory configurations for programs 
under TAXO, The following paragraphs ovtline the processes for achiev- 
ing any of these configurations, The maximum allowable memory for each 
task in any configuration is 32,752 words, 


Program with Task Segment only 


Figure 1-3A illustrotes a program with a task segment only. The fol- 
lowing process generates this configuration: 


1, The source progrom is assembled (perhaps in several modules), 


2. If more than one object module is involved, the object code is linked 
into one module by the link editor. 


3. The linked object module is installed on a progrom file as a task 
segment using the IT (Install Task) SCI command, or as a function 
of the Link Editor, 


4. The installed task is executed using an XT (Execute Task) SCI command 
or on Execute Task supervisor call, 


Program with Task Segment and System Common Segment 


Figure 1-3B illustrates the memory configuration of a program with o task 
segment and o system common segment. The process which generates this 
configuration is the same as the process required to generate a task 

only configuration, except that System Common must have been defined at 
system generation and the task itself must issue a Get Common supervi- 
sor call during execution, A Release Common supervisor call may be exe- 
cuted to release the common segment, 
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1.6.3 Program with Task Segment _and one or two Procedure Segments 


Figures 1-3C and 1-3E illustrate a program with a task segment and pro- 
cedure segment(s). The following process generates this configurotion: 


1, The various modules of the program are separately assembled, 


2. The two (or three) segments of the program are linked by the link 
editor. To be separately loadable, the procedures must be specified 
by the PROCEDURE command to the Link Editor. 


3, The procedure(s) are installed using the Install Procedure (IP) SCI 
command (or by the Link Editor). 


4, The task segment is installed using the Install Task (IT) SCI com- 
mand and using the procedure IDs specified during the Install Pro- 
cedure (IP) command. 


5, The installed task is executed using on XT (Execute Task) command 
or an Execute Task supervisor call, 


1.6.4 Program with A Task Segment, Procedure Segment, and System Common 


1.7 


1.7.1 


Figure 1-3D illustrates this configuration. The process which generates 
this configuration is the some as the process which generates the pro- 
gram with a task segment and one procedure segment configuration ex- 
cept that system common must have been defined at system generation 
and the task itself must issue a Get Common Supervisor Call during 
execution, A program consisting of a task segment and two procedure 
segments may not access system common, 


Overlays 


Overlays ore parts of a program ("phases") which share memory and are 
loaded from o program file into memory during program execution, Over- 
lays ore used to reduce the memory needed for a program by loading 
only part of the program initielly and loading overlays as needed to 
complete the program, 


The memory requirements of « program can be reduced significantly if 

it is split into two or more overlays which share the same overlay oreo. 
A control phase, or root phase, which is not overlaid must be added 

to the program to control the loading of the overlays. However, over- 
lays increase execution time by the time required to load the overlays. 
An effective scheme is to overlay seldom used phases of a program and 
retain common code in the root segment. 


Overlay Structures 

Overlay structures are defined by the user and generated by the Link 
Editor. Refer to the Link Editor Reference Manual on organizing over- 
lay structures, 
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words SEGMENT 
MAXIMUM 32 BYTE 
e BOUNDARY 
32K a” 
WORDS 
MAXIMUM ' 
SYSTEM 
A. SINGLE SEGMENT 
PROGRAM 1 COMMON ! 


@. SINGLE SEGMENT PROGRAM 
WITH SYSTEM COMMON 


PROCE OURE 
SEGMENT 


25.axt 22.550, 
JOUNDARY INDARY 
nak a “ 
MAXTMUM : 
32K 
worps TASK 
MAXIMUM SEGMENT 32 OYTE 
a UNA 
H i 
Cc. TwO SEGMENT i) 
PROGRAM Ve: eons : 
J 
Li.  — a 


D. TWO SEGMENT PROGRAM 
WITH SYSTEM COMMON 


PROCEDURE 
SEGMENT 32 BYTE 
a7 BOUNDARY 
vores "SecMeNT. 
wok0s 
Mantua 2 Byre 


C. THREE SEGMENT PROGRAM 


Figure 1-3, Task Memory Configurations 
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1.7.2 Overlay Loading 


In the root segment or in phases in memory, the user loads overlays 
from a progrom file into memory with Load Overlay supervisor calls as 
described in Section 3, Since control returns to the instruction after 
the Load Overlay coll, care should be taken that the call itself (or 
the present workspace) is not overlaid, 


‘The user can include an automatic load overlay manager which manages 


the loading of overlays in a program during link edit by using a =anK 
Editor LOAD command. 


1.7.3 Relocatable Overlays 
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Overlays are usually loaded into memory at the natural load address 
determined during link edit. However, a user may load an overlay else- 
where in memory. Modules installed as relocatable overlays in a pro- 
gram file can be relocated by the load overlay call. This enables users 
to load overlays where space is available rather than where link edited. 
However, the overlay cannot have references to other overlays. 


Programming Prohibitions 


Programs installed in TAXO cre either privileged or non-privileged. 
Privilege is enforced by TAXO and the TA 1630 hardware. Most programs 
are non-privileged and may not use the following TA 1630 assembly lan- 
gvoge instructions: 


e Computer Control Instructions (RSET, IDLE, LREX, LIMI) 
e@ Real Time Clock Instructions (CKON, CKOF) 
e Mapping Instructions (LMF, LDD, LDS) 


e I/0 Instructions (SBO, SBZ, TB, LDCR, STCR) when the CRU address is 
greater than E00\,. 


Further, non-privileged tasks may not use the following supervisor 
calls (SVs): 


Install Disk Volume Delete Task 

Unload Disk Volume Delete Procedure 

Initialize Disk Volume Delete Overlay 

Allocate Disk Space Assign Space on Program File 
Direct Disk I/0 Get System Pointer Table Address 
Open File Unblocked Suspend Awaiting Queve Input 
Install Task Kill Task 

Install Procedure Read/Write TSB 

Install Overlay Read/Write Task 


Initialize Time and Date 


Finally, no task (either privileged or non-privileged) may access memory 
outside its assigned range, It may, however, request additional memory 
using the Get Memory supervisor call, provided the total program size 
remains less than or equal to 32,752 words. : 


Any prohibited access (instruction, supervisor call, or memory) causes 
a fatal task error and TAXO aborts the task (unless end action is spe- 
cified). 
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1.9 Task Management ~ 


Task Management in TAXO deals principally with how the CPU and user me- 


mory are allocated, ‘ 


1.9.1 Task Scheduling 


TAXO Task Scheduling involves the manner in which a task is chosen to 
receive control of the CPU and the allocating or deallocating of the 
CPU when scheduling takes place. 


TAXO always allocates the CPU to the highest priority task awaiting 
execution, However, certain conditions may cause a task's priority to 
be changed if the Task Sentry is enabled. Refer to paragraph 1.9.3 of 
this manual for information regarding Task Sentry. 


Task Scheduling occurs when one of the following conditions exist: 
e An external interrupt bids up a task. 
e The executing task suspends. 


e Task Sentry lowers the priority of the executing task (if Task 
Sentry is enabled). 


e The time slice allocated to a task expires (if time slicing is 
enabled). 


e Atime delayed task is due to become active. 


When an event external to the computer occurs, an interrupt may be 
used to signal the Task Scheduler that a specific user program be 
scheduled to run, The operating system then reschedules the tasks o- 
waiting execution because the newly-bid task may be the highest prio- 
rity task in the system. 


If the executing task suspends (relinquishes control of the CPU), the 
Task Scheduler allocates control of the CPU to the next highest prio- 
rity task in the system, If Task Sentry is enabled and has lowered the 
priority of the currently executing task, the tasks awaiting execution 
are rescheduled in case a task of higher priority is now in the system. 


If time slicing is enabled, tasks execute for a fixed interval of time. 
Upon expiration of a time slice, a rescheduling of the tasks is per- 
formed. Time Slicing allows tasks of equal priority to share the CPU 
in a round-robin fashion. 


If a time delayed task becomes active, a rescheduling of the tasks in 
the system is performed to insure that the highest priority task is 
executing. 


NOTE 
Task Sentry, time slicing, and time slice duration are System 
Generation (SYSGEN) options. 
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1.9.2 Dynamic Memory Management 


TAXO manages memory by allocating memory to high priority tasks and 
rolling out low priority tasks. When a task that is in memory is se- 
lected for execution, a check is made to see if ao higher priority task 
is waiting to be loaded into memory. If a higher priority task is wai- 
ting, an attempt is made to load it, Allocating memory for the higher 
priority task may cause the low priority task to be rolled out of memory, 


To obtain memory for the current task, TAXO copies (or rolls out) 


. existing users of memory to the roll file which is a system file on 


disk. The following are eligible for rollout: 

e File blocking buffers (written to appropriate file). 

@ Disk-resident tasks. 

e Disk-resident procedures (after attached tasks are rolled). 


Once rolled out, a task remains on the roll file until it is selected 


for a time slice and brought back into memory (rolled in). Only the 


memory-resident file, blocking buffer, and tasks installed as memory- 
resident on the system progrom file are exempt from rollout, 


1.9.3 Task Sentry 
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An inherent characteristic of the TAXO Task Scheduling scheme is that 
tasks which are CPU-bound may lock out all tasks of a lower priority 
level, Task Sentry, a SYSGEN feature, monitors CPU-bound tasks and 
lowers their priority by one-after a specified number (specified during 
SYSGEN) of 50 millisecond intervals has elapsed, This allows lower prio- 
rity tasks to be allocated CPU time. When a CPU-bound task suspends 
itself (for example, and I/0 request), the Task Sentry resets the sus- 
pended task's priority to its installed priority level. In the case of 
floating priority tasks, their priority is reset to either priority 
level 1 or 2. 


Task Attributes 


Tasks have the following attributes in TAXO. 
1, Privileged 

2. System 

3. Priority 

4, Residency 

5, Replicatability 
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1.10.1 Privilege 
Privilege is explained in the paragraph on programming prohibitions. 
Basically, the typical user tosk is non-privileged and is prohibited 
from doing certain system functions. A task is specified as privileged 
or non-privileged by a parameter in the Install Task (IT) SCI commend, 
or by a parameter in the Install Task supervisor call, 


1.10.2 System 


A task is either a system task or a user task, System tasks have the 
following characteristics: 


e Execute in privileged mode. 


e Execute in system memory address spoce (coexistent with other por- 
tions of the system). 


1,10.3 Priority 
The TAXO Operating System requires that each task have a defined prio— 
rity level. TAXO provides the following 132 levels of priority: 


(Highest) 0 Critical System Tasks (Reserved for TAXO) 
R1 - R127 Real-time priorities 
1 Foreground interactive tosks 
2 Foreground compute bound tasks 
(Lowest) 3 Background tasks 
(Floating) 4 (Priority 1 and 2) 


‘ Priority level _zero is intended for the most critical system functions 
and is reserved for TAXO internal use only. The remainder of system 
tasks are distributed appropriately among the lower priority levels 
with regard to their relative importance, 


Reol-time priorities provide the user the copability to supercede all 
except the most important system tosks, For applications which require 
prompt occess of the CPU, TAXO foregoes some routine maintenance of 
system duties in an effort to schedule real-time tasks, 


Priorities one, two, three, and four are designed to satisfy require- 
ments of most installations. Priority levels one and two ore used mainly 
by programs requiring user interaction. Priority level one gives quick 
response for progroms interacting with the user's terminal, while prio- 
rity level two is adequate for progroms requiring multiple disk accesses. 


For progrom requiring user interaction and multiple disk accesses, prio— 
rity level four automatically switches between priority levels one and 
two as the program executes. Therefore, progroms requiring user atten- 
tion can be serviced quickly. 


Priority level three is for programs executing in batch mode, which 
require no user interaction, 
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1.10.4 Residency 


1.10.5 


1.117,1 


1.11.2 


Tasks may be memory-resident (always in memory) or disk-resident (in 


memory when active, but possibly rolled to disk when not active), Most 


user tasks should be disk-resident to free memory for other tasks and 


- since some supervisor calls depend on the TAXO rollin/rollout facility. — 


Memory-resident tasks must be installed on the system program file and 
are effectively disk-resident tasks until the system is rebooted, Cer- 
tain support features which depend on rollin/rollout (such as dynamic 

memory allocation) are not available to a memory-resident task, 


- Once. resident, memory-resident tasks occupy memory, even if tommineted: 


until they are deleted from the system program file and the system is 
rebooted, : 


Tasks are installed on progrom files by the Install Task SCI command 
(or the install task supervisor call) or by the Link Editor (refer to 
the Link Editor Reference Manual), Tasks are deleted from program 
files by the Delete Task SCI command or the delete task supervisor 
call, Residency is a parameter which is supplied at installation. 


Replicatability 


Tasks specified to be replicatable may have multiple copies concurrently 
in memory. Replicatable tasks are frequently used in multiterminal sys- 
tems, allocating one (or more) copies for each terminal, Replicatability 
is a poremeter which is supplied ot installation. 


Task Termination 


Tasks executing under the TAXO may terminate normally or abnormally. In 
either case, the task should make provision for termination. If a task 
does not explicitly invoke termination, it either loops infinitely or 
it attempts to violate its memory bounds and causes abnormal termina- 
tion, A task in an infinite loop may be killed externally by using the 
Kill Task SCI command or by pressing first the RESET key, then the CMD 
key. 


Normal Terminction 


To terminate normally, a task executes an End Task supervisor coll, 
TAXO then releases the task's resources and takes it out of execution. 
Disk-resident tasks disappear from memory. Memory-resident tasks remain 
in memory and occupy space but do not execute, 


Abnormal Termination 


If a task commits a fatal error (illegal instruction, supervisor call, 
or memory reference), two things can happen: 


1. If the task Transfer Vector includes an end action oddress, the rovu- 
tine at thot address is activated. Typically, the end action routine 
executes an End Action Status supervisor coll, outputs the returned 
data, and executes an End Task supervisor call. However, it is pos- 
sible for the end action routine to implement error recovery proce- 
dures. If the end action routine commits errors, TAXO unconditionally 
oborts the task, 


2. If the task Transfer Vector entry for end action is less than 16, TAXO 
unconditionally aborts the task. 
In either case, the error is reported to the system log, if one is defined. 
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1.12 Reentrant_Progromming 


A procedure is called reentrant if it may be shared by several users, 
perhaps in a multitask environment, without loss of data, A procedure 
is called “pure” if it contains only unmodifiable code and constant 
data; i.e., it is, effectively, "read only". Pure procedures cre re- 
entrant, Moreover, every program may be split into a pure part con- 
taining only executable code and a "dirty" part containing volatile 
data and code modified at run time, 


TAXO supports shared pure procedures. (Non-reentrant procedures may be 
shared, but TAXO does not guorantee dota integrity.) Further, the Lan- 
guage Processors (e.g., macro assembler) and the Link Editor support a 
special construction which simplifies reentrant coding. 


If an assembly language program uses the PSEG directive to denote exe- 
cutable code ond the DSEG directive to denote data, the link editor 
separates the program, putting executable code into a procedure seg- 
ment and dota into the task segment. If the PROCEDURE directive is 
used during link edit, the procedure segment created by the link edit 
is shared (and reentrant), 


For further information, consult the Assembly Language Programmer's 
Guide and the Link Editor Manual, 


Appendix C contains an exomple of reentrant progromming. 
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2 SUPERVISOR CALLS 


2.1 


Introduction 


User tasks interface with the TAXO Operating System by issuing Super- 
visor Calls (SVCs), which request that the operating system perform 

a specific function. SVCs are provided within TAXO to perform device 
and file I/0, task control, service functions, memory control, and 
file utilities. SVCs are explicitly used in assembly language tasks, 
whereas high-level language statements are processed by the appropriate 
interpreter or compiler and are translated to the particulor SVC re- 
quired to perform the requested operation, If a statement to access a 
particular SVC is not availoble in the high level language, the user 
can write an assembly languoge subroutine to access the SVC. The fol- 
lowing paragraphs define what a supervisor call is and define the for- 
mat for writing a supervisor call in assembly language. 


2.2 Supervisor Call Definition 


Supervisor calls are implemented using the TA 1630 Computer Assembly 
Language Extended Operation (XOP), with the XOP number being 15, and 


tthe effective address of the XOP instruction being thet of a supervi- 


sor call block, The execution of the extended operation causes execu- 
tion control to be passed to the operating system (for more detailed 
information on the XOP instruction, see Assembly Language Progrommer's 
Guide). The supervisor coll block referenced in the XOP instruction 
contains the necessary parometers for the requested operation, with 
the first byte of the call block always being a code indicating the 
type of service that is to be performed by the operating system. Fi- 
gure 2-1 illustrates the sequence followed when an XOP instruction is 
issued for a supervisor call, 


XOP POINTS TO CAL: BLOCK 


CALL SLOCK 
svc CODE RETURNED 
NUMBER STATUS 


OTHER 
ARGUMENTS OR 
RETURNED VALUES 


Figure 2-1. XOP Call Processing 


2.2.1 


2.2.2 
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Coding ao Supervisor Coll 


Within the assembly language program, supervisor calls can be written in 
either of two ways. The first method is to use the XOP instruction, with 
the extended operation level defined as 15 and the effective address 
being that of the supervisor call block. The following is an example 

of this coding technique using a supervisor call block that hes been 
labeled BLOCK: 


XOP @BLOCK, 15 PERFORM EXTENDED OPERATION 15 . 


* USING THE SUPERVISOR CALL BLOCK AT 
* THE ADDRESS DEFINED BY THE SYMBOL 
BLOCK 


The second method of coding supervisor calls involves the use of a 
Define Extended Operation (DXOP) directive, which allows the user to 
assign a symbol to be used in the operator field of XOP instructions. 
Prior to coding any supervisor calls, the user defines Extended Opera- 
tion 15 as being equivalent to some symbol, and that symbol may then 
be used in place of the XOP instruction when coding supervisor calls, 
Within this document, Extended Operation 15 has been defined by the 
following directive to be the symbol SVC: 


DXOP SVC, 15 


Supervisor calls coded after the DXOP directive may use SVC in the ope- 
rator field, as in the following: 


SVC (a) BLOCK 


which specifies that extended operation 15 be performed using the call 
block at the location defined by the symbol BLOCK, 


Defining Supervisor Coll Blocks 


Supervisor call blocks are defined within the user task by the use of 
DATA, BYTE, and TEXT directives, Note that the DATA directive is used 
to define word (16-bit) entries, the BYTE directive is used to define 
byte (8-bit) entries, and the TEXT directive is used to define charac- 
ter string entries. Since some of the call blocks must be aligned on a 
word boundary, either the DATA directive should be used, which forces 
alignment on a word boundary, or the definitions for the block of data 
should be preceded by cn EVEN directive; which also forces the block 

to begin on o word boundary, Good coding practice is to begin all super- 
visor call blocks on a word boundary. 


The number of porameters required within the call block varies for each 
supervisor coll. However, the first byte (byte 0) of the call block 
must contain the code of the type of service that is required of the 
operating system, In addition, the second byte (byte 1) of the call 
block is generally used by the system to return a status or error code. 
Therefore, it is recommended that the user provide statements within 
the calling task to test the error code byte for the existence of an 
error and, if an error has occurred, to process the error. 


NOTE 

TAXO uses XOP R15,15 (alternatively SVC R15) to implement 
breakpoints. Do not use workspace register 15 os a super- 
visor call block. 
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When coding a supervisor call block, it is advisable that entries used 
to store dato returned by the system or entries containing variable data 
be labeled to facilitate accessing of the dato by the user task. The 
label associated with the first byte of the call block is used as the 
effective operand in the’ XOP (or DXOP equivalent) instruction to refe- 
rence the block. The following is a somple of a supervisor call block 
and the call required to access it: 


TAX! SOSMAC 947075 s€ 06:37:34 TUESDAY, AUG 02, 1977, 
PAGE 0001 
0001 OT ‘TASKI’ 
0002 ‘ 
0003 + TASK HEADER 
0004 ty 
0005 REF PROCI 
0004 0000 0078’ DATA TWS.PROCI.0 TRAGFER VECTOR 
0002 ANNO 
0004 0000 
0007 TEF ALUN). ALNUM, OPEN, OLNUM 
0008 EF WRITEL. MILAM. DRITED, ALAM 
reed : DEF CLOSE. CLNUN. RELEAS. RLNUM 
ool! 3 ASSIGN LUNO BLOCK 
0012 : 
0013 0006 ed 
GO14 0004 00 ALIN 0.0 10,STATUS 
0007 00 
OOS 0008 $1 ALND CPCONE 
0016 0009 10 ALNUM BYTE 510 LUNO NUMBER 
0017 000A 0000 DATA 0,0.0.0.0,0 WOT USED 
000c 0000 
OOOE 0000 
0010 0000 
0012 0000 
0014 0000 
one oy o ALLFLG BYTE 540.0 UTILITY FLAGS-GENERATE LUNO 
0019 0018 0000 DATA 0.0.0200.020.0.0 NOT USED 
OO1A 0000 
QO1C 0000 
OO1E 0000 
0020 0000 
0022 0000 
0024 0000 
0026 0000 2 
0028 6000 ve 
0021 * OPEN PRB 
007 
22 EVEN 
0024 002A «(00 «OPEN BYTE. 0.0 10, STATUS 
00my «= 00 
9078 OF  cuen BeS CR. ro BE FILLED I 
O02? 003 OD BYTE 0:0 USER FLAGS 
ones Bi) 9 ITE 0:0 DEVICE TYPE 
0029 0032 0000 BATA 0.0.0 
0034 0000 
0036 0000 
0030 ° : 
0031 ¢ OWITE OE PO 
0032 e 
Soe B88 oo unter BY 0,0 10, STATUS 
003900. 
fae Gee OF MILMM BYTE OF WMO TO Be FILLED IN 
0037 063C =—-00 BYTE 0,0 SYSTEM, USER FLAGS 
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TRS! SNGNAC 947075 s€ 08237234 TUESDAY, AUG 02, 1977. 
PAGE 0002 
on3D 
O38 WIE 5092" DATA TEXT! BUFFER ADDRESS 
NOI? 004) 9000 DATA TEXTIL CHAR al 
0040 0042 0000 DATA TEXTIL CHAR 
0041 0044 0000 BATA Oo 
0042 * 
0043 + WRITE TWO PRs 
0044 ¢ 
045 0046 EVEN 
4s peed 60 WRITE2 BYTE 0.0 10, STATUS . 
O47 0043 0B BYTE “8 WRITE ASCIT 
038 049 00 WOLNLM BYTE 0 LUN, TO BE FILLED IN 
0049 Ne 4 RITE 6,0 SYSTEM, USER FLAGS 
5050 NOME O0AS’ Hata TEXT? KUFFER ADDRESS 
0051 OO4E ON0D DATA TEXT CHAR COUNT 
52 0050 0000 DATA TEXTOL CHAR COUNT 
(453 0052 0000 DATA 0 ; 
OOs4 « 
OSS ® CLOSE PRA 
0056 ¢ 
OnS7 OY EVEN 
O88 0054 «00 «CLOSE RYTE 6.9 19, STATUS 
COED 0054 Ot RYTE *1 CLIKE 
060 0057 «(00 CLAM BYTE 9 LUND. TO 3€ FILLED IN 
Mal 0088 = 00 RITE 9.0 SYSTEN, USER FLAGS 
we | . 
0042 008A 0000 PATA 0.0.0.0 wy WEEN 
OO NNN) : 
OO5E 0000 
004) 0000 
+ 
ONGS * RELEASE LUND 
045 ¢ 
O66 6042 EVEN 
WAT 0062 00 ~RELEAS BYTE 9.0 10, STATIS 
NMI 1H 
A068 144 93 BYTE *93 PELEASE LUND 
O49 ODES 00 PLNUM BYTE tlw, TO PE FILLED IN 
0070 0044 0000 DATA 9,0,0,0,0,0,0,0.0 ROT USED 
62 0000 
Q04A 0000 a 
OAC 1000 
0000 
0070 0000 
0072 0000 
074 1000 
0078 0000 
0071 + 
M72 ¢ TASK t DATA 
0073 * 
78 0078 ws 
0075 9098 


BSS 1682 
TEXT! EXT “1 AM TASK ONE’ 
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5076 


53 
7 


2/5 


SDSMAC 947075 #€ 08:37:34 TUESDAY, AUG 02, 1977. 
’ 


4 
53 
48 
20 
* 


TEXTIL EQU $-TEXT! 
TEYT2 TEXT “NOW I AM DONE’ 


Samnressesuaencan 


TEXTA EQU §-TEXT2 
END 


Pan 


Md 


PAGE 0003 


PROCI 


0001 
0002 
0003 
0004 
000% 
9006 
9007 
0003 
0009 
0010 
oo1t 
0012 
o013 
0014 6000 


0015 0004 
0016 0008 
0017 O00Cc 


0018 0010 


* 
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13213852 MONDAY. JAN 23. 1976. 
U PAGE 0001 


PROCEDURE SEGMENT 1| 


IDT 
DEF 
REF 
REF 
REF 
REF 


“PROC1~“ 

PROC1 

PROCZ 

ALUNO,. ALNUM, OPEN, OLNUM 
WRITEL.WILNUM, WRITES. W2LNUM 
CLOSE. CLNUM, RELEAS. RLNUM 


PROCEDURE ONE 


Eau 


END 


' 


s 
@ALNUM, RO MUVE LUNO NUMBER TO PRB‘’S 


RO. @OLNUM 

RO, @WiLNUM 

KO. @W2LNUM 

RO. @CLNLIM 

RO, @RLNUM 

@OPEN. 15 OFEN LYING 
QWRITE1,15 WRITE TEXT 1 
e@PROCS GO TO PROC 2 


“a 


etre 
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SBSMAC 947075 #E 08243222 TUESDAY, AUG 02, 1977. 


PAGE 0001 


PROCEDURE SEGMENT 2 

ToT = *PROC2’ 

fEF PROC? 

REF WRITE2, CLOSE RELEAS 
PROCEDURE TWO 


ew § 

MOP OURITE2,15 WRITE TEXT 2 

XOP @CLO0SE.15 CLOSE LUNO 

XOP ORELEAS.15 RELEASE LUMO SeDUMMY IF NOT FILEss 
xOP @E0T. 15 END OF TASK 

CONSTANT DATA 

BITE 4,0 END OF TASK 

Ew 


SRGMAC 947075 e€ © 08243225 TUESDAY, AUG 0:. 1977. 


0620-0000 
NO ERRORS 


PAGE 0001 


Z 
i 
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3 PROGRAM SUPPORT CALLS 


3.1 


Generol 


Program support calls ore supervisor calls that are used in application 
progroms to request the services of TAXO for operations not directly re- 
lated to I/0 operations. The types of program support calls provided by 
TAXO are divided into three categories - program control calls, memory 
control calls, and miscellaneous calls. Each of these categories and 
the individual calls are discussed and defined in this section. Super- 
visor calls for device and file input and output are discussed in se- 
parate sections within this manual, 


The user should note that the calls discussed in this section are 
opplicable only to assembly language programs ond routines. The high- 
level languages use statements in their respective repertoires to 
achieve the same results, where opplicoble, as the supervisor colls, 

If no statement is provided within the high-level languoge that accesses 
the desired supervisor call, an assembly language module may be written 
that issues the supervisor call, and is callable from the high-level 
language program. Assembly language routines must be linked to the 
high-level language object module by using the link editor, as pre- 
viously defined in this document, 


The supervisor calls considered to be program support colls are shown 
in table 3-1 and are defined in subsequent parographs. In all of the 
following discussions relating to supervisor calls, it is assumed that 
supervisor call extended operation has been defined to equal the mne- 
monic SVC, in other words, the statement DXOP SVC, 15 was previously 
defined within the assembly language program. 


Within the following descriptions of the supervisor calls, byte one 
within each call block is defined, in most cases, as the error code 
byte, If an error occurs during the execution of the requested super- 
visor call function, the system returns an error code in byte one, It 
is the responsibility of the calling task to check this error byte to 
determine whether the requested operation has been completed normally. 
If the byte contains o non-zero value, on error has occurred and the 
calling task must provide the code to handle the error in the proper 
manner, All error codes are documented in the ERROR MANUAL, 


Within the description of the call blocks for the supervisor calls, 

the error code byte, byte one of the call block, is labeled os ERRC, 
Defining the error code byte by a separate BYTE directive and label- 
ing it allows the calling task to easily access the byte to determine 
whether on error has occurred, The following series of statements 
could be used within the calling tosk to test the error code and branch 
to the correct routine if an error has occurred. 


MOVB (ERRC,@ERRC COMPARE THE ERROR CODE TO ZERO 
JNE ERRTN IF NOT ZERO, GO TO ERROR ROUTINE 
: IF ZERO, CONTINUE NORMAL PROCESSING 


Note that on available register can be used as the destination operand 
for this dummy move, Using a register is faster and saves one word of 
memory. 
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Table 3-1. Program Support Supervisor Calls 


Call Program Control Calls 


Execute Task 

Activate Suspended Task 
Scheduled Bid Task 

Load an Overlay 

End of Task 

End of Program 

Time Delay 

Change Priority 

Poll Status of Tosk in Ter- 
minal Tosk Set 
Unconditional Wait 

Activate Time Delay Task 
Get Parometers 

Self Identification 

End Action Status 

Reset End Action 

Map Program Name to ID 

Do not Suspend 


Memory Control Calls 


Get Memory 

Release Memory 

Get Common Data Address 
Return Common Data Address 


Miscellaneous Calls 


Getdata 

Putdata 

Convert Binary to Decimal 
Convert Decimal to Binary 
Convert Binary to Hexadecimal 
Convert Hexadecimal to Binary 
Date and Time 

System Log 

Retrieve System Information 


Hexadecimal 
SVC Code 
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3.2 Program Control Supervisor Calls 


Program Control supervisor calls cre those thot directly affect a task: 
those that execute o task, suspend a task, or terminate a task. The 
following paragraphs def,ine each of the Program Control supervisor 
calls and give the format of the supervisor call block for each, the 
supervisor call code, and the errors returned by the system. In addi- 

' tion, on example of each Program Control supervisor call is given. 


3.2.1 Execute Task Supervisor Call - Code 28B;, 


The Execute Task supervisor call is used to initiate the execution of 
a task that has been installed on any program file, If the task speci- 
fied in the call is already active and wos defined as being replice- 
table (a task is defined to be replicatable when it is installed), 
another copy of the task is placed in execution. The replicated task 
can share procedure with previous activations of the task. If the 
call is issued for a task that is active but is not replicatable, 

the system returns an error to the calling task. 


The call block for the Execute Task supervisor coll is twelve bytes 
in length and must be aligned on a word boundary, The entries in the 
supervisor call block ore defined as follows: 


Byte 0 -. Contains the code for the Execute Task call and must be 
2816 e 


Byte 1 - The byte is used by the system to return on error code, 
if necessary. 


Byte 2. - Contains the ID of the task to be executed, Note thot 
the user specifies the installed ID of the task and the 
system returns the runtime ID in this byte, 


Byte 3. - Contains user specified flags with the following meanings: 


Bit O - Set to zeros, 

through 

Bit 3 

Bit 4 - When set to one, this bit causes the calling 
task to be terminated immediately after 
issuing the Execute Task SVC, 


Bit 5 «= When set to one, this bit indicates that the 
task specified in byte 2 is a controlled task. 
This flag is used in conjunction with the sys- 
tem debug utility. 


Bit 6 - When set to one, this bit forces the initiol 
state of the executed task to be unconditionally 
suspended. This flag is also used in conjunc- 
tion with the system debug utility. 


Bit 7 - Setting this bit to one causes TAXO to suspend 
the calling tosk until the called task (speci- 
fied in byte 2) has terminated, 
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Byte 4 - These bytes ore used to poss user specified parameters to 
through the called task, The called task must issue a Get Para- 
Byte 7 meters supervisor call to obtain the parometers. 

Byte 8 - Contains the user specified ID of the station (terminal) 
with which the called task is to be associated. If the 
user specifies O (zero), the colled task will be associa- 
ted with the some station as the colling tosk. If the 
user specifies >FF, the called task will not be associated 
with a station, 

Byte 9 - Contains the user specified logical unit number (LUNO) 


assigned to the program file on which the called task is 
installed, If the user specifies zero, the system assumes 
thot the single system program file is to be used, 


Byte 10 - Must be set to O (zero) by the user. 
Byte 11 - Must be set to 0 (zero) by the user. 


The following example of an Execute Tosk supervisor call specifies 
that task 3B), be loaded from the progrom file associated with LUNO 
TAig and without an associated station. The task is not controlled, 
is not to have an initial state of unconditioneally-suspended, is to 
pass the hexadecimol ASCII representation of the choracters HELP to 
the colled task, and the calling task is to suspend until task 3B 


terminates. 
EVEN FORCE ALIGNMENT ON A WORD BOUNDARY 
SCBA BYTE >2B8 CODE FOR EXECUTE TASK 
ERRC BYTE >00 SET BYTE ONE TO ZERO 
TID BYTE >3B INSTALLED ID OF TASK TO BE EXECUTED 
FLG1 BYTE >01 CALLING TASK SUSPENDED UNTIL CALLED TASK 
TERMINATES 
PAR TEXT ‘HELP’ PASS HELP TO CALLED TASK 
FLG2 BYTE >FF TASK ASSOCIATED WITH NO STATION 
LUN BYTE >1A LUNO OF THE PROGRAM FILE 


BYTE 00,00 SET BYTES 10 AND 11 TO ZERO 


Within the procedure portion of the calling task, the following stcte- 
ment is used to initiate the Execute Task supervisor call: 


svc @SCBA 


Issuing the preceding call causes task 3B), to be loaded from the pro- 
grom file and executed, If the task issues a Get Parometers call, it is 
passed the ASCII choracters HELP. 
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An example of a supervisor call block to perform the Activate Suspended 
Task call for a task with a runtime ID of 3Ci, would be os follows: 


SCBB BYTE 07 ACTIVATE SUSPENDED TASK CODE 
ERRC BYTE 00 SET BYTE ONE TO ZERO 
TID BYTE >3C RUNTIME ID OF TASK TO BE ACTIVATED 


Within the procedure portion of the calling task, the following state- 
ment is used to perform the operation: 


svc (a) SCBB 


If task 3C,, had previously been suspended by an Unconditional Wait call, 
it would be activated by the preceding statement. If task 3C,, had not 
been suspended, but is suspended by an Unconditional Wait statement sub- 
sequent to the preceding call, it would be immediately reactivated. 


3.2.3 Scheduled Bid Tosk Supervisor Coll - Code IFy 


@ The Scheduled Bid Task supervisor call is used to activate a task at a 
specified time, Note that the Scheduled Bid Task supervisor call can 
only be used for tasks that have been installed on the single system 
program file and that were designated as being non-replicatable. The 
Scheduled Bid Task supervisor call operates in one of two modes, de- 
pending on whether the task being scheduled is the calling task or 
another task. 


If the task issuing the Scheduled Bid Tosk call is scheduling itself, 

. then the call functions as a time delay. Control does not return to 
the calling task until the specified date and time. If the task being 
scheduled is not the calling task, control returns to the calling task 
after the requested task has been functionally placed active witha . 
time delay set to start execution at the specified time and date. For 
reliable results, the specified time should be more than the current 
time by at least several seconds. 


The call block for the Scheduled Bid Task supervisor call consists of 
14 bytes and must be aligned on a word boundary. The bytes within the 
block have the following significance: 


Byte O - Contains the hexadecimal code of the Scheduled Bid Task 
call ond must be IFig. 


Byte 1 - Set to 0 (zero) by the user. If on error occurs, the sys- 
tem returns on error code in this byte. 
Byte 2. - Contains the user specified installed identifier of the 
task to be bid. . 
Byte 3) - The value of the year in which the bid task is to be ac- 


tivated, The year is specified relative.to 1900 A.D. For 
example, the year 1978 is expressed as 7819. 


Byte 4 - Contain the ordinal (Julian) date on which the task is to 
and be activated. For example, -the date Feb. 10 is expressed 
Byte 5 as 41\,. 


1630/SVC/SC1/0281/e 


3/7 


Byte 6 - Contains the user specified hour at which the task is to 
be activated. The hour is based on twenty-four hour no- 
tation. For example, 11:00 PM is expressed as 23,.. The 
volue must be less than or equal to 23;,. 

Byte 7 - Contains the user specified minute at which the task is 
to be activated, The minute must be less than or equal to 
5910 e 

Byte 8 - Contains the user-specified second at which the task is 

, to be activated, The second must be less than or equal to 
5919 ° 

Byte 9 - Reserved. Initialize to zero, 

Byte 10 - These bytes are optional, and if specified by the user, 

through contain porometers that are to be passed to the bid task. 

Byte 13 3 


The following exomple shows the call block for a Scheduled Bid Task ope- 
ration to activate task 3D), at 11:59:59 on February 10, 1978. In the 
example, the parometers ABCD are passed to the bid task, 


EVEN ALIGN ON WORD BOUNDARY 

SCBC BYTE >I1F CODE FOR SCHEDULED BID TASK 

ERRC BYTE 00 SET BYTE ONE TO ZERO 

TID BYTE >3D TASK ID IF THE BID TASK 

YEAR BYTE 78 YEAR THE TASK IS TO BE ACTIVATED 

DAY DATA 41 JULIAN DATE OF THE ACTIVATION DATE 

HOUR BYTE 23 HOUR THE TASK IS TO BE ACTIVATED 

MIN BYTE 59 MINUTE AT WHICH THE TASK IS TO BE ACTIVATED 

SEC BYTE 59 SECOND AT WHICH THE TASK IS TO BE ACTIVATED 
BYTE 00 SET BYTE NINE TO ZERO 


MSG TEXT ‘ABCD’ PASS ‘ABCD’ TO TASK 


Within the procedure portion of the calling task, the following state- 
ment is written to perform the Scheduled Bid task using the information 
at the memory location specified by SCBC: 


SVC (@)SCBC 


3.2.4 Load an Overlay Supervisor Call - Code 14), 


The Load Overlay supervisor call is used to load a specified overlay from 
disk into memory, Within the call block, the user specifies the overlay 
number, the LUNO of the overlay’s progrom file, and the address at which 
the overlay is to be loaded. The call block consists of seven bytes and 
is aligned on a word boundory, The bytes within the call block have the 
following meanings: 


Byte O - Contains the code of the Load Overley call, The user must 
specify 14,,. 
Byte 7 - Error code byte. Returned by the system. 


Byte 3 
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Contain the optional user specified load address for the 
overlay. This parometer is used along with information 
supplied when the overlay was installed to determine the 
load address and whether relocation is to be performed, 
The following rules apply: 


1, If bytes two and three of the Load Overlay supervisor 


call block ore zero or equal to the natural load ad- 

dress of the overlay (the natural load address is de- 
termined when the overlay is link edited), the over- 

lay is loaded at the natural load address without re- 
location. 


If bytes two and three of the call block are not 
equal to either zero or the natural load address, the 
overlay is loaded at the address specified in bytes 
two and three, Relocation is performed only if relo- 
cation was specified when the overlay was installed, 


NOTE 

If relocation is to be performed, the user-supplied 
load area must provide spoce for the overlay and 
the relocation bit map, which is loaded immediately 
following the overlay, The size of the relocation 
bit map, in bytes, is calculated as follows: 


SBM=2* [ses 8h Truncated 


Where: 


SBM is the size of the bit map and SOV is the size 
of the overlay, in bytes. Denotes rounding up to 
the next integer. 


The total size of the user load area (in bytes) when 
relocation is to be performed is SOV + SBM, 


Contains the number of the overlay that is to be loaded. 
The user must specify an overlay number less than or 
equal to 25519. 


Contains the user specified LUNO of the program file upon 
which the overlay is resident. This LUNO must not be open 
when the call is issued. Two specicl case values of this 
field are supplied for user convenience: 


1. If the LUNO field is zero, the overlay is loaded from 


the single system program file. 


2. If the LUNO field is FF,,, the overlay is loaded from 


the same progrom file as that of the colling task. If 
this feoture is to be used, the user should not re- 
lease LUNO FF, . 
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The following example shows the call block to load overlay number 6A, 
from LUNO 1Bi,into memory at the natural overlay load address. 


EVEN F 
SCBD BYTE >14 CALL CODE 
ERRC BYTE 0 ERROR CODE 
LADD DATA 0 NO RELOCATION 
OVNM DATA >6A OVERLAY NUMBER 96 
LNUM BYTE >1A LUNO OF PROGRAM FILE OVERLAY IS ON 


Within the procedure portion of the calling task, the Load Overley func- 
tion is called by the following statement: 


SVC (@)SCBD 


End of Task Supervisor Call - Code 04), 


The End of Task supervisor call is used to terminate execution of the 
calling task. The call block consists of one byte, which contains the 
coll code, and need not be aligned on a word boundary, An example of 
the call block is as follows: 


SCBE BYTE 4 END OF TASK CALL CODE 
The function is called as follows: 
SVC @) SCBE i 


The End of Task supervisor coll performs such functions as releasing 
the local device tables, releasing task memory and the task stcotus 
block for disk-resident tasks, reinitializing the task status block for 
memory resident tasks, ond clearing of any outstanding breakpoints, 


End_ of Progrom Supervisor Call - Code 16y, 


The End of Program supervisor call is identical to the End of Task coll, 
except that the call code specified in the call block is 16. This call 
is supported only for compatibility with previous systems, ond its use 
is not recommended, 


Time Delay Supervisor Call - Code 02 


The Time Delay supervisor call is used to suspend the calling task for 
the specified minimum number of full 50-millisecond clock periods. Spe- 
cifying zero implies a delay of from zero to 50-ms, specifying one im 
plies a delay of from 50-ms.to 100ms, and so forth. A task in time de- 
lay may be reactivated before the end-of the specified time interval by 
another task issuing an Activate Time Delay.Task supervisor call (code 
OE 14 inclusive). The following is an exomple of the block required to 
delay a task for 10 seconds: 


SCBF DATA >0200 CALL CODE AND SET BYTE ONE TO ZERO 
INTV . DATA 200  ~——sCODELAY -~-FOR 200 TIME INTERVALS 


Within the procedure, the call to perform the Time Delay operation using 
the preceding call block is written as follows: 


SVC  (@)SCBF 
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3.2.8 Change Priority Supervisor Call - Code 11g 


The Change Priority supervisor call allows the calling task to change 
its own priority. This is valuable in a situation where a task that 
normally runs at low priority needs 'to perform a critical operation. 
Use of this call allows a task to change its priority to a higher or 
lower level. 


The call block for the Change Priority call consists of two bytes and 
does not need to be aligned on a word boundary, Byte zero of the call 
block contains the call code (11,,) and byte one contains the new prio- 
rity level, On return from the SVC call the priority in effect prior 

to the call is returned in byte one, which must be between O and 3 
(inclusive) or between 1 and 127 (inclusive) with the real-time prio- 
rity (high order) bit set, 


An example of a call block required to change the calling task's prio- 
rity level to real-time priority 80,, is as follows: 


SCBG BYTE >11 CODE OF THE CHANGE PRIORITY CALL 
PRI BYTE >D0O SET PRIORITY TO DECIMAL 80 


Within the procedure portion of the task, the following statement causes 
\ the Change Priority call to be performed: 


svc (QSCBG PERFORM EXTENDED OPERATION 15 USING 
* THE CALL BLOCK AT LOCATION SCBG 


Specification of an illegal priority will result in an error code of 
>80 being returned in byte 1 of the call block. 


The TAXO operating system requires that each task have a defined prio- 
rity level, There are 132 priorities available: Level 0 (highest), 127 
real-time priorities (denoted R1 - R127), level 1, 2, and 3 (lowest). 

Also, priority four is a dynamic priority which is level one while in 

the interactive mode, and otherwise is level two. 


Level zero is intended for the most critical system functions and is 

_ thus reserved for TAXO internal use, The remainder of the system tasks 
are appropriately distributed among the lower priorities with regard to 
their relative importance. 


Real-time priorities provide the user the capability to supercede all 
except the most important system tasks, For these applications which 
require an expeditious access to the CPU, TAXO will forego some routine 
maintenance of system duties in an effort to schedule real-time tasks. 


Real-time priorities are represented at the SVC call block level as prio- 
rity numbers with the high order bit set in the byte specifying the 
priority level. 


as 
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Priorities one, two, three, and four are designed to satisfy the require- 
ments of most installations. Priority level one gives quick response for 
programs which interact with the user's terminal, while priority level 
two is adequate for programs which perform multiple disk accesses. Both 
levels one and two are used mainly by programs which require some inter- 
action with a user. For programs which do both user interaction and 
multiple disk access, priority four will automatically switch between 
priorities one and two as the program executes. This advantageous to 
the overall system in that programs that require user attention can be 
serviced quickly. Priority level three is for batch execution, which 
requires no user interaction. 


Bit zero of the priority field, when set, indicates real-time priority 
as shown below: 


nny ZERO OF THE PRIORITY FIELD, WHEN SET 
DICATES REAL TIME PRIORITY AS SHOWN BELOW 


PRIORITY 
! 7 


[e) 


Poll Status of Task Supervisor Call - Code 35), 

The Poll Status of Task supervisor coll is used to determine the status 
of a special task within the set of tasks assigned to a specified ter- 
minal, Tasks are assigned to a specific terminal when they are placed in 
execution by the Execute Task supervisor coll. 


NOTE : 

If the task was terminated using an SVC 33,, (Kill Task), it is 
possible for the Poll Status call to return a code of FF, (task 
is not in the system) while the task's LUNOs ore still assigned. 
This is due to a time interval between the task being removed from 
the active task queve and having its LUNOs closed and released. 


The call block for the Poll Status of Task consists of eight bytes, which 
must be aligned on a word boundary and have the following significance: 


Byte O - Contains the supervisor call code. Must be set to 35,, 
by the user, 


If an error occurs, the system returns an error code in 
this byte. 


Contains user specified flags with the following meanings: 


Byte 1 


Byte 2 


Bit 0 - If set to one, a station number is specified in 
byte 4, If set to zero, only tasks on the station from 
which the SVC was executed are polled, 


Bits 1 through 7 - Reserved. User must set to zero. 


The task state code for the specified task is returned in 
this byte by the system. The task state codes are defined 
in table 3-2, 


Byte 3 
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Byte 4 - The user-specified station number of the task set con- 
taining the specified task. Note that if byte 2, bit 0 
is set to 0, no station number is specified in this byte. 
If the user specifies FF,, here, the state of any task in 
the system with the specified ID is returned. 


Byte 5 - The user-specified runtime ID of the task whose status is 
desired. 

Byte6 - Set to 0 (zero) by the user. 

and 

Byte 7 


An example of ao Poll Status of Task coll block to determine the status 
of a task with a runtime ID of 3F,, and that is assigned to terminal 
eight is shown in the following: 


EVEN 
SCBG BYTE >35 CALL CODE 
ERRC BYTE 0 SET ERROR BYTE TO ZERO 
FLAG BYTE >80 STATION NUMBER SPECIFIED 
TSKC BYTE 10) ' TASK STATE CODE RETURNED HERE 
STAN BYTE 8 STATION NUMBER 
TID BYTE >93F TASK RUNTIME ID 

DATA .¢) SET BYTES 6 AND 7 TO ZERO 


The Poll Status function using the above call block is called by using 
the following statement within the procedure portion of the calling task: 


SVC (a) SCBG 


Note that the calling task has to obtain the task state from byte 3 of _ 
the call block. ; 


3.2.10 Unconditional Wait Supervisor Call - Code 06), 


The Unconditional Wait supervisor call suspends the calling task indefi- 
nitely. The task is reactivated by the issuance of an Activate Suspended 
Task supervisor call that specifies the Task Runtime Identifier of the 
suspended task, One level of "memory" is supported so that if an Acti- 
vate Suspended Task call is issued prior to the task being specified, 
end an Unconditional Wait call for the task is issued after the Activate 
call, the task is immediately reactivated, 


The call block for the Unconditional Wait call consists of one byte, 
which contains the coll code and does not need to be aligned on o word 
boundary. The following is an example of the Unconditional Wait call 
block: 


SCBH BYTE 6 SUSPENDED CALLING TASK 


- The Unconditional Wait service is called from the procedure section of 


the task by the following statement: 


SVC  (@)SCBH 
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Table 3-2. Task State Codes 


Code 

(Hexadecimal ) Significance 

00 ’ Active task 

01 Active task 

04 Terminated task 

05 Task in time delay 

06 Suspended task 

07 © Currently executing task 

08 Task awaiting character input 

09 Task awaiting completion of 1/0 

OA Task awaiting assignment of a device for I/0 

08 Task awaiting disk file utility services 

oc Task awciting compress services 

aD Task awaiting file management services 

OE Task awaiting overlay loader services 

OF Task awaiting initial load 

11 Task awaiting disk management services 

12 Task awaiting tape management services 

13 Task awaiting system overlay loader services 

14 Task awaiting task driven supervisor call processor 

15 Task awaiting Get Memory services 

7 Task suspended for activation of a called task 

18 Task awaiting dicgnostic task services 

19 Task awaiting completion of any 1/0 

TA Task awaiting memory management services 

1B Task is eligible for roll-out when requested 
I/0 completes 

1c Task is being rolled out 

1D Suspended for Initiate I/0 threshold 

1E Suspended for Locked Directory 

iF Suspended for Task Management directory buffer 

24 Task suspended for queve input 

FF Dummy task state 


Activate Time Delay Task Supervisor Call - Code OE 


The Activate Time Delay supervisor call is used to activate a specified 
task that is in a time delay state, A task enters the time delay state 
when a Time Delay supervisor call is issued within the task, The call 
block for the Activate Time Delay call consists of three bytes and does 
not require alignment on a word boundary. Byte zero contains the code 
for the call, which must be 0E,,, byte one is set to zero by the user 
and, if an error occurs, the system returns an error code in byte one, 
and byte two contains the runtime identifier of the task to be activated, 
The error code returned is the task state, The following is an exemple 
of a supervisor call block to activate task 1B),: 


SCBH BYTE >0E SUPERVISOR CALL CODE 
ERRC BYTE oO SET BYTE ONE TO ZERO 
TRID BYTE >1B TASK IDENTIFIER (RUNTIME) 
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The following statement appears in the procedure portion of the calling 
task to perform the Activate Time Delay Task function: 


svc @SCBH PERFORM EXTENDED OPERATION 15 USING THE 
BLOCK AT LOCATION SCBH 


3.2.12 Get Parameters Supervisor Coll - Code 17, 


The Get Parameters supervisor call is used to obtain the task parameters 
passed to the calling task by the Execute Task or Bid Task supervisor 
calls, The supervisor coll block for this coll contains six bytes, 
aligned on a word boundary, which have the following significance: 


Byte O - Contains the call code, the user must specify 17, . 


Byte 1 - Set to 0 (zero) by the user. 

Byte 2 - The system places the parameters specified in the Execute 
through Task call into these four bytes. 

Byte 5 


The following is an example of a supervisor call block for the Get Pora- 
meters call: 


EVEN 
SCBI BYTE >17 CALL CODE 
ERRC BYTE 0 ERROR BYTE 
PAR1 DATA 0 SET TO ZERO 
PAR2 DATA 0 SET TO ZERO 
’ An example of the call to perform the Get Parometers function is as 
follows: 
SVC (@) SCBI 


3.2.13 Self Identification Supervisor Call - Code 2Ey, 


The Self Identification supervisor call allows the calling task to obtain 
its runtime ID, which may differ for the installed ID of the task. The 
call block consists of six bytes, aligned on a word boundary, with the 
user specifying the call code (2E,,) in byte zero, and the system return- 
ing the runtime ID in byte one, the installed ID in byte two, and the ID 
of the station that the task is associated with in byte three, Bytes 

four and five are reserved and are set to zero by the user. Note that 

the system returns FF,, in byte three if the task is not associated with 
o terminal, An example of the supervisor call for Self Identification is 
shown in the following: 


EVEN 
SCBJ BYTE >2E CALL CODE 
> RTID BYTE 0 SYSTEM RETURNS RUNTIME ID HERE 
INID BYTE 0 SYSTEM RETURNS INSTALLED ID HERE 
STID BYTE ¢) SYSTEM RETURNS STATION ID HERE 
DATA 0 SET TO ZERO 


The call to request the operation defined by the preceding block is 
written as follows: 


svc (@SCBJ PERFORM EXTENDED OPERATION 15 USING 
THE CALL BLOCK AT LOCATION SCBJ 
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3.2.14 End Action Status Supervisor Call - Code 2Fig 


3.2. 15 


The End Action Status supervisor call is used to determine the Workspace 
Pointer, Status, and Program Counter register contents when on error 
causes abnormal terminating of a task. In addition, the system returns 
the code of the error that caused termination. This call is issued 
during end action execution, End action execution occurs when an error 
aborts the task, causing the system to transfer control to the end ac- 
tion routine specified by the user in the third word of the task. 


The supervisor call block for the End Action Status call consists of 

10 bytes, aligned on a word boundary, with the user specifying the call 
code in byte zero, The system returns the error code in byte one (the 
error codes are listed in ERROR MANUAL), the Workspace Pointer register 
contents in bytes two and three, the Program Counter register contents 
in bytes four and five, and the contents of the Status register in bytes 
six and seven, Bytes eight and nine are reserved. An example of the call 
block is shown in the following: 


EVEN 
SCBK BYTE >2F CALL CODE 
ERRC BYTE 0 ERROR CODE RETURNED HERE 
WPPREG DATA 0) WORKSPACE POINTER REGISTER CONTENTS 
PCREG DATA 0 PROGRAM COUNTER REGISTER CONTENTS 
STREG DATA 0 STATUS REGISTER CONTENTS 

DATA 0 SET TO ZERO 


The following is an example of the code to initiate the End Action Status 
call using the preceding block: : 


svc (@) SCBK PERFORM EXTENDED OPERATION FIFTEEN USING 
THE CALL BLOCK AT LOCATION SCBK 


* 


Reset End Action Supervisor Call - Code 3Ej¢ 


The Reset End Action supervisor call is used to reset a calling task's 
end action capability if the run ID specified in the call block is zero; 
otherwise, the task ID specified in the call block will have end action 
reset. If the Reset End Action call is ‘executed and the task being spe- 
cified has end action set, no error code is returned. 


Under TAXO, as task is allowed to take end action one time, but the 
Reset End Action allows a task to take end action more than one time. 
The task that requires more than one attempt ot end action may issue 
this SVC, or a controlling task may reset end action for another task. 
The Reset End Action SVC must be executed each time end action is taken 
and will not reset end action if the task has been terminated vie a 
Kill Task request. 


The supervisor call block for the Reset End Action call consists of four 
bytes, aligned on a word boundary, with the user specifying the call code 
in byte zero. The system returns the error code in byte one, and the 
run-time ID in byte two. Byte three is reserved. An example of the call 
block is shown in the following example: 


EVEN 
SCBK BYTE >3E CALL CODE 
ERRC BYTE ERROR CODE RETURNED BY SYSTEM 


0 
RTID BYTE 0 SYSTEM TASK RUN ID, OR ZERO 
BYTE 4) SET TO ZERO 
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The following is an example of the code to initiate the Reset End Ac- 
tion call using the preceding block: 


SVC @SCBK Perform extended operation 15 using the call block at 
location SCBK. ; 


3.2.16 Map Program Name to ID Supervisor Call - Code 3ly, 


The Map Program Nome to ID supervisor call is used to determine the in- 
stalled ID of any procedure, task, or overlay from the module name. 
Alternatively, the user can issue the call with no program name speci- 
fied, but with the installed ID of the module specified, and the sys- 
tem returns the module name, The call block for the Mop Program Name 

to ID call consists of 16 bytes, aligned on a word boundary, with the 
bytes having the following definitions: 


Byte QO - Contains the user-specified code for the Map Program 
Name to ID call, Must be 31,,. 


@ Byte 1 - Set to 0 (zero) by the user. If an error occurs, the 
system returns on error code in this byte. 


Byte 2. - User-specified flags with the following definitions: 


Bits 0 and 1 

00 indicates a task's ID; or nome is requested, 

O01 indicates a procedure’s ID; or nome is requested, 
10 indicates an overlay's ID; or nome is requested. 
Bit 2 

© indicates the ID is requested. 

1 indicates the program nome is requested, 


Bits 3 - 6 - Not used. 

Bit 7 

1 LUNO assigned to progrom file is open. 

O LUNO assigned to program file is not open. 


Byte 3. + Reserved, Set to O (zero) by the user, 

@ Byte 4 - If the system is to return the ID, these bytes contain the 
through eight alphanumeric ASCII character nome of the task, over- 
Byte 11 lay, or procedure, with trailing blanks, If the request 


is for the nome of a task, overlay, or procedure, the 
system returns the nome in these bytes, 


Byte 12 - The user-specified LUNO of the program file the task, 
procedure, or overlay is on, If zero, no assignment is 
implied and the single system progrom file is used. 


Byte 13 - If the request is for an ID, the system returns the in- 
stalled ID in the byte, If the request is for a program 
name, the user specifies the installed ID in this byte. 


Byte 14 - Reserved, Set to zero by the user. 
through 
Byte 15 


< 
- 
8 
SS 
- 
2 
3 
S$ 
3 
a 
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The following example illustrates a call block to determine the program 
nome of a task (1B;,) installed on a program file with the LUNO assign- 
ment 2Ci,: 


EVEN } 
SCBL BYTE >31 CALL CODE 
ERRC BYTE 0 ERROR BYTE, SET TO ZERO 
FLGA BYTE >20 SPECIFY REQUEST FOR TASK NAME 
BYTE .¢) INITIALIZED TO ZERO 
NAME BSS 8 BLOCK OF EIGHT BYTES FOR NAME 
LNUM BYTE >2C LUNO 
TID BYTE >1B TASK ID 
DATA i?) 


The following example shows the call block to determine the installed 
ID of a procedure installed on the program file assignment to LUNO 23,, 
and with a program nome of CALCFOUR: 


EVEN 
SCBM = BYTE >31 CALL CODE 
ERRC BYTE 0 ERROR BYTE, SET TO ZERO 
FLGA BYTE >40 PROCEDURE ID REQUESTED 
BYTE 0 RESERVED, SET TO ZERO 
NAME TEXT 'CALCFOUR' — PROCEDURE NAME 
LNUM «BYTE >23 LUNO NUMBER 
TID BYTE =O ID RETURNED HERE 
DATA OO ce ine 


The following calls cre examples of those written to perform the Map 
Program Name to ID supervisor call using the preceding blocks: 


SVC (@SCBL PERFORM EXTENDED OPERATION FIFTEEN USING 
* THE CALL BLOCK AT LOCATION SCBL 

SVC (@)SCBM PERFORM EXTENDED OPERATION FIFTEEN USING 
* THE CALL BLOCK AT LOCATION SCBM 


Do Not Suspend Supervisor Call - Code 94 


The Do Not Suspend supervisor call causes the system to override the time 
slice for the calling task by inhibiting the system from suspending 

the task, The task may suspend itself by executing an I/0 supervisor 
coll, or a Time Delay, Woit for I/0, or an Unconditional Wait supervi- 
sor coll, The supervisor call block contains two bytes, and need not 

be aligned on a word boundary, Byte 0 contains the code, and byte 1 con- 
tains 0 or a positive number, When byte 1 contains 0, the task will not 
be suspended for 200 ms. When byte 1 contains a positive number, the 
task will not be suspended for that number of system units (50 ms). 


Suspension of a task may be inhibited for a period of from 50 ms. to 
12,750 seconds (1 to 255 50 ms. periods). 
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The following is an example of coding for a supervisor call block for 
a Do Not Suspend call: 


= BYTE 9, 15 INHIBIT SUSPENSION OF CALLING TASK 
FOR 750 MS; 


The following call is an example to perform the Do Not Suspend super- 
visor call using the preceding call block: 


svc (@)SCB PERFORM EXTENDED OPERATION FIFTEEN USING 
THE CALL BLOCK AT LOCATION SCB 


The Do Not Suspend supervisor call should be used instead of a LIMI 
instruction having an operand of zero to inhibit termination of task 
at the end of the current time slice. When a task manipulates a data 
structure that is used by several tasks, the task should complete its 
alterations to the data structure before any of the tasks that use the 
data execute again. The Do Not Suspend supervisor call allows such a 
task to lock out other tasks while changing the data. 


3.3 Memory Control Supervisor Colls 


Memory Control supervisor calls allow the calling task to expand its 
memory space, to access system common memory, to contract its memory 
space, or to release system common memory. Before the user attempts 
to use any of these calls, certain considerations must be taken into 
account, 


A task installed in TAXO is able to access three distinct portions of 
memory by using the three pairs of memory mapping address registers 
that ore assigned to each task, Basically, a task itself can use one, 
two, or all three of these registers, A task installed as one object 
module, consisting of a task division and a procedure division, uses 
one mop register; oa task installed as one task division and a separate 
procedure division uses two of the map registers; and a task installed 
as one task division ond two separate procedure divisions uses all three 
of the mop registers. The use of the registers ond the distinction be- 
tween separate tasks and procedures is transparent to the user since 
the link editor provides all the links between portions of a task and 


“sets the registers, 


Calls to expond or contract the actual task memory orea do not require 
an additional map register, they simply modify the register that defines 
the limits of the task, Note, however, that the call to access system 
common memory uses one of the registers. The call to return the system 
common memory releases the map register used, If the task itself uses 
oll three registers, no calls may be made to access system common memory. 
The user should also note that while system common memory is mapped into 
the task's address area, no calls can be issved to expand or contract 
the task's actual memory size. 


NOTE 


re TAXO does not keep the history of Get and Release memory. calls. 


For this reason, it is not possible to release a specific block of 
memory, except at the high end of memory when the task itself re- 
members the specific block acquired. 


1630/svVC/SCI/0281/e 


3/19 


3.3.1 Get Memory Supervisor Call - Code 12% 


The Get Memory supervisor call is used to increase the amount of memory 
allocated to the calling task. Within the supervisor call block, the 
user specifies the number of contiguous 32-byte blocks of memory that 
are to be obtained for the task, The task is rolled out and then rolled 
in to an expanded area in memory that equals the original size of the 
task plus the additional memory requested by the Get Memory call. The 
Get Memory call cannot be issued when the task is memory-resident, nor 
can the Get Memory call be issued when system common memory is mapped 
into the task'’s address space. The user must also consider that the 
maximum amount of memory available to an individual task is 64K bytes, 
Any number of Get Memory calls may be issued within a task as long as 
the preceding requirements are met. Memory requests are for an integral 
number of 32-byte blocks, The address of the first 32-byte block ob- 
tained is returned to the calling task in its workspace register 9, 


The call block for the Get Memory supervisor call consists of four 
bytes, aligned on a word boundary, with each byte having the following 
significance: 


Byte O - Contains the code for the Get Memory call. Must be set 
to 12), by the user when the block is initialized. 


Byte 7 - If on error occurs during execution of the Get Memory 
coll, the system returns on error code in this byte. 


Byte 2. - The user specified number of 32-byte blocks that are to 
and be allocated to the calling task.- 


The following example shows the call block for a Get Memory call that 
requests the allocation of 16 contiguous 32-byte blocks of memory to the 
calling task: 


EVEN 
SCBB BYTE >12 CALL CODE 
ERRC BYTE 0 INITIALIZE ERROR CODE BYTE TO ZERO 
BLKC DATA 16 NUMBER OF MEMORY BLOCKS REQUESTED 


An exomple of the call used within the procedure portion of the calling 
task to perform the Get Memory call using the preceding block is as. 
follows: 


SVC  (@SCBB 


3.3.2 Release Memory Supervisor Call - Code 13% 


The Release Memory supervisor call is used to return to the system all 

task memory above the address specified in workspace register 9, The 

Release Memory call cannot be issued if the task is memory-resident 

nortan it be issued if the task currently has system common memory 

mapped into its address space. The Release Memory call couses the task's 

map register to be modified to address only the remaining task memory _ 
~ area, 
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The call block for the Release Memory supervisor call consists of four 

bytes, aligned on a word boundary, with each byte having the following 

significance: 

Byte O - Contains the code of'the Release Memory call. Must be 
set to 13), by the user, 


Byte 1} - If an error occurs during execution of the Release 
Memory call, the system returns an error code in this 
byte. 

Byte 2 - Not used. 

and 

Byte 3 


The following call block is an example of a Release Memory call block 
that would release memory beyond the address >8400 in the task area, 


EVEN 
& SCBC BYTE >13- CALL CODE @ 
ERRC BYTE 0 INITIALIZE BYTE ONE TO ZERO 


BLKC DATA 0 


Within procedure section of the calling task, the following statements 
are used to perform the Release Memory function: 


LI R9,>8400 
SVC (@)SCBC RELEASE MEMORY ABOVE ADDRESS >8400 


Note that after this call is made, an attempt to release an address 
higher than >8400 would result in a fatal task error. 


3.3.3 Get Common Data Address Supervisor Col] - Code 101% 


The Get Common Data Address supervisor call is used to obtain the address 
of the beginning of the intertask common memory area, and to return that 
address in task workspace register 9. The size of the intertask common 
memory area is returned to the calling task in its workspace register 8, 
The size of the intertask common memory crea is o system parameter spe- 
cified at SYSGEN time, 


@ To properly use the Get Common Dato Address supervisor call, the user x ) 
must understand that each task is allowed to use only three segments of 
memory at one time, as described at the beginning of this section. 


The supervisor call block for the Get Common Data Address call consists 
of two bytes, which need not be aligned on a word boundary, with the 
following significance:  - 


Byte O - Contains the code for the call, Set to 10,, by the user, 


Byte 1 - If the system detects an error while processing the call, 
an errer code is returned in this byte. If the three 
allowable segments of memory are already in use when 
this call is issved or if a common area was not included 
during SYSGEN, the system returns FFi,. 
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NOTE 

This supervisor call is included for compatibility with previous 
systems ond is not recommended for new designs, The alternate 
technique of using a common procedure element is preferred since 
procedures may be linked with the task to resolve references. 


The following is an example of a Get Common Dato Address call block: 


SCBD BYTE >10 CALL CODE 
ERRC BYTE 0 ERROR BYTE SET TO ZERO 


Within the procedure portion of the task, the following statement is 
used to call the Get Common Data Address function: 


SVC @SCBD 


3.3.4 Return Common Data Address Supervisor Coll - Code 1B, 


The Return Common Data address supervisor call is used to release the 
system common memory obtained by the Get Common Data Address supervisor 
call, Note that issuing this call releases the common data area and 
allows the task to request another segment of memory. The limitation 
of three memory segments is discussed previously in this section. 


The call block for the Return Common Data Address call consists of one 
byte that contains the call code (1B\,), and does not need to be aligned 
on a word boundary. An example of the call block is as follows: 


SCBE BYTE >1B CALL CODE 


An exomple of the statement provided in the procedure section of the 
calling task to request the operation defined by the preceding block 
is as follows: 


SVC  (@)SCBE 


3.4 Miscellaneous Supervisor Calls 


3.4.1 


TAXO provides the user with a number of supervisor calls to perform 
various functions, including intertask communications, binary/decimal 
and binary/hexadecimal conversion services, time and date service, and 
system log functions. The following paragraphs describe the calls asso- 
ciated with these groupings. 


Intertask Communications 


The Intertask Communications supervisor colls allow the user to transfer 
data between tasks by use of a dynamic memory buffer. The two calls 
available, described in the following paragraphs, are Getdata and Put- 
dota, 


To avoid duplication of message subqueve IDs, byte three of the super- 
visor calls, it is recommended that the run-time task ID of one of the 
tasks involved in the dato transfer be used, A combination of the self- 
identification (2£1,), Execute Task (2B,,), and Get Parometers (17), ) 
Supervisor Calls can be used to accomplish identification of the sub- 
queves with one of the task's run-time IDs. This is the mode of identi- 
fication used by Sort Merge and COBOL Sort function. 
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3.4.1.1 Getdata Supervisor Call - Code 1Dj, 


The Getdata supervisor call retrieves a message from the TAXO dynamic 
memory area and moves the message to the specified user buffer. The user 
supplies an identifier (ID) in the call that specifies a channel that 
contains the message. Note that messages are queved in o first-in, first- 
out order, so that the oldest message with the specified ID is returned. 
An error is returned when no message with the specified ID is found. 


The call block for the Getdata call consists of 12 bytes and must be 
aligned on a word boundary. The bytes of the call block have the fol- 
lowing significance: 


Byte O - Contains the call code. Must be set to 1D),. 


Byte 1 - If an error occurs during execution of the call, the 
system returns an error code in this byte. If no mes- 
sage with the specified ID is found, an FF is re- 
turned. 


® Byte 2. - User-specified flogs with the following meanings: 


Bit 0 - If set to one, every message in the subqueve 
indicated by the ID is deleted and no message is returned, 
If set to 0, a message is deleted from the subqueve only 
when it is returned, 


Bits 1-7 - Reserved. Initialize to zero. 


Byte 3) - The user-specified ID of the subqueve containing the 
message. 

Byte 4 -~ The user-specified oddress of the buffer in which the 

and message is to be ploced, Must be on o word boundary. 

Byte 5 

Byte 6 - The user-specified maximum length of the buffer specified 

and in bytes four and five, Must be an even number of bytes, 

Byte 7 

Byte 8 - The actual number of characters in the message. This va- 
& and lue is returned by the system ond is always less thon or 

Byte 9 equal to the buffer length. Messages longer than the buf- 


fer are truncated and the part truncated is lost, 


Byte 10 - Reserved, Initialize to zero. 
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The following exomple of a Getdata call block requests that a message 
with a subqueve ID of 7A,, be returned to the task in the buffer at 
location BUFF1, with a maximum buffer length of 80-characters. 


EVEN ! 
SCBF BYTE >1D CALL CODE 
ERRC BYTE (8) ERROR BYTE, INITIALIZE TO ZERO 
FLG1 BYTE 0 DO NOT PURGE SUBQUEUE 
MID BYTE >7A MESSAGE SUBQUEUE ID 
BADR DATA BUFF 1 ADDRESS OF BUFFER THAT IS TO RECEIVE MESSAGE 
MLGT DATA 80 MAXIMUM LENGTH IS 80-CHARACTERS 
ACTL DATA 0 INITIALIZE BYTES EIGHT THROUGH ELEVEN TO ZERO 


RESV DATA 0 


Within the procedure portion of the calling task, the Getdata call is 
requested as follows: 


SVC (@SCBF 


* 


3.4.1.2 Putdate Supervisor Call - Code 1Cig 


‘ 
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The Putdata supervisor call is used to transfer messages from a user 
buffer to the TAXO dynamic memory crea for subsequent retrieval by a 
Getdata supervisor call. The messages written to the dynomic memory 
area by the Putdate supervisor call are placed in channels thet have 
the same identifier as the message, The messages are placed in the sub- 
queves in a first-in, first-out manner, so that the oldest message in 
the subqueve is obtained first when o Getdata call is issued with that 
identifier, The Putdata operation is unsuccessful when a message buf- 
fer cannot be allocated, 


The call block for the Putdate supervisor call consists of twelve bytes, 
aligned on a word boundary, with each byte having the following signifi- 
cance: 


Byte o - Contains the code of the Putdata operation, Set to IC, 
by the user, 

Byte 1 - Reserved for system returned error codes, If the system 
cannot allocete o buffer for the message, FF,, is re- 
turned in this byte. 

Byte 2. - Reserved, Initialize to zero. 

Byte 3. - The user-specified identifier of the message. 

Byte 4 - The user-specified address of the task buffer that con- 

and tains the message. Note that this must be an even address 

Byte 5 (on a word boundary). 

Byte 6 - Not used, 

and 

Byte 7 : 

Byte 8 - The user-specified length of the buffer that contains 

and the message. This must be an even number of characters. 

Byte 9 

Byte 10 - Reserved. Initialize to zero. 

and 


Byte 11 


3.4.2 


3.4.2.1 
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The following exemple of a Putdata call block requests that a message 
be written from the task buffer at location BUFF2, which has a maximum 
length of 80-characters, and that the message is to have an identifier 
of IFi,. 


EVEN 
SCBG BYTE >I1C CALL CODE 
ERRC BYTE 0 ERROR BYTE, INITIALIZE TO ZERO 
RESV1 BYTE 0 INITIALIZE BYTE TWO TO ZERO 
MID BYTE >IF IDENTIFIER FOR THE MESSAGE 


BADR DATA BUFF2 BUFFER ADDRESS 

RESV2 DATA 0 

BLGT DATA 80 LENGTH OF THE BUFFER 

RESV3 DATA 0 INITIALIZE BYTES TEN AND ELEVEN TO ZERO 


The following code is an example of what is written in the procedure 
portion of the calling task to call the Putdata function using the pre- 
ceding call block: 


SVC (@SCBG 


* 


Binary/Decimal and Binary/Hexadecimal Conversion Services 


Supervisor calls available in TAXO to provide binary-to-decimal, deci- 
mal-to-binary, binary-to-hexadecimal, and hexadecimal-to-binary conver- 
sion services, The following parogrophs describe each of these calls 
and provide examples of the call blocks for each. 


Convert Binory-to-Decimal - Code OAj, 

The Convert Binary to Decimal supervisor call is used to convert a binary 
value, which must be in task workspace register 0, to its equivalent 
decimal value, which is represented in ASCII, The supervisor call block 
for the Convert Binary to Decimal call consists of eight bytes, which 

do not have to be aligned on a word boundery, ond which hove the follow- 
ing meoning: 


Byte QO - Contains the code for the call and is set to OA,,. 
Byte 1 - Reserved, Initialize to zero, 
Byte 2. - ASCII sign, If the value being converted is negative, 


the system returns an ASCII minus sign in this byte, If 
the converted value is zero or positive, o blank is re- 
turned in this byte. 


Byte 3. - ASCII decimal value. The system places the converted 
through value, right justified with leading blanks, into these 
Byte 7 bytes, 


The following example illustrates the coding of a supervisor call block 
for a Convert Binary-to-Decimal operation: 


SCBH BYTE >A CALL CODE 

ERRC BYTE 0 SET ERROR BYTE TO ZERO 

WRD1 BYTE 0 FIRST TWO BYTES FOR DECIMAL VALUE 
WRD2 BYTE 0 NEXT TWO BYTES FOR DECIMAL VALUE 
WRD3 BYTE 0 LAST TWO BYTES FOR DECIMAL VALUE 


= 
ooo 


’ 
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The following is an example of the code used in the procedure portion 
of the calling task to perform the Convert Binary to Decimal function 
using the preceding call block: 

SVC (@SCBH , 


+ 


The following examples show several binary valves in register 0 and the 
results returned by the Convert Binary to Decimal call in bytes two 
through seven of the call block: 


Register 0 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 Byte 7 


000144 2046 2016 2016 2016 2016 316 
7FFF y, 2%, 33 32% 376 366 Wig 
FFFF y, 2D 16 216 20 % 2016 2016 31h, 


3.4.2.2 Convert Decimal-to-Binary Supervisor Call - Code OBi, 


The Convert Decimal-to-Binary supervisor call is used to convert a de- 
cimal value, represented by ASCII characters in bytes two through seven 
-of the supervisor call block, to a binary value and to place that binary 
value in task workspace register 0, The supervisor call block for this 
call consists of eight bytes and does not need to be aligned on a word 
boundary, The bytes in the call block have the following meanings: 


Byte O - Contains the code for the call ond is set to 0By. 


Byte 1 - Error code. If one or more of the characters in bytes 
3 through seven are not valid, the system returns FF), . 


Byte 2 - The user-specified sign of the value to be converted. 
Allowable entries are: 


2B,, - The ASCII representation of a plus sign (+). 
2Di4 - The ASCII representation of the minus sign (-). 


2016 - The ASCII representation of a blank ( ), which 
indicates the valve is positive or zero. 


30\4 - The ASCII representation of a zero (0), which 
indicates that the value is positive or zero, 


Byte 3. - The ASCII representation of the value to be converted os 
through specified by the user, Right-justified with leading 
Byte 7 blanks, 


The following example shows o supervisor call block for converting the 
decimal value 378 to binary: 


SCBI BYTE >0B CALL CODE 
ERRC BYTE 0 ERROR CODE, INITIALIZE TO ZERO 
SIGN BYTE ‘+’ PLUS SIGN TO INDICATE POSITIVE OR ZERO VALUE 


HEXADECIMAL ASCII REPRESENTATION OF 378 
CDAT TEXT ‘00378' CONVERT 378 DECIMAL TO BINARY 


The following is an example of a call within the procedure portion of the 
calling task to perform the decimal to binary conversions using the pre- 
ceding call block and placing the binary value in the calling task's 
workspace register 0: 


SVC  @)SCBI 
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The following ore examples showing typical hexadecimal ASCII represento- 

tions of decimal values and the binary values returned in register 0. 

The examples also show the value returned in byte one of the call block: 
! 


3.4.2.3 Convert Binary-to-Hexodecimal Supervisor Coll ~ Code OCj, 


The Convert Binary-to-Hexadecimal supervisor call is used to convert a 
binary value, which must be in the calling tosk's workspoce register 0, 
to the ASCII representation of the equivalent hexadecimal value. The 
supervisor call block consists of six bytes and does not need to be 
aligned on a word boundary, 


ByteO - Contains the call code (OC, ). 
Byte 1 - Error code returned by system, 
Bytes 2-5- Returned hexadecimal value. 


The following is an exomple of a Convert Binary to Hexadecimal call 
block: 


SCBH BYTE >0C CALL CODE 

ERRC BYTE 0 ERROR CODE 

CNU1 BYTE 0, 0 FIRST TWO BYTES OF CONVERTED VALUE 
CNU2 BYTE 0, 0 NEXT TWO BYTES OF CONVERTED VALUE 


The following is an example of the statement within the procedure por- 
tion of the calling task that would perform the Convert Binary-to-Hexa- 
decimal operation using the preceding call block and the binary value 

in register 0, we, 


SVC (a) SCBJ 


The following examples show typical binary values and the results of 
the conversion as placed in bytes two through five of the call block: 


Register O Byte 2 Byte 3 Byte 4 Byte 5 


00011, 3016 3016 3016 3116 > 
7FFF ie 714 by Cg 
FFFF y6 46% 4616 4616 4616 
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3.4.2.4 Convert Hexadecimal-to-Binary Supervisor Call - Code 00), 
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The Convert Hexadecimel-to-Binary supervisor call is used to convert 
user-specified hexadecimal values, represented in ASCII, in bytes two 
through five of the call block to a binary value and to store the con- 
verted value in the calling tosk's workspace register 0, The supervisor 
call block consists of six bytes, which do not need to be aligned on a 
word boundary. 


Byte O - Contains call code (ODi,). 
Byte 1 - Error code returned by system. 
Bytes 2-5- ASCII representation of number to be converted. 


The following example shows the call block to convert 03F4,, to a binary 
value: 

SCBH BYTE >0D CALL CODE 

ERRCD BYTE >0 ERROR CODE 

CNV TEXT >03F4 CONVERT >03F4 TO BINARY 


The following is an example of the code used within the procedure por- 
tion of the calling block to perform the conversion using the preceding 
call block: 


SVC (@) SCBH 


The following examples show the results of converting typical ASCII re- 
presentations of hexadecimal digits and the value place in byte one: 


Byte 2. Byte 3 Byte 4 Byte § Register O Byte } 


3014 3016 3014 316 0001,, Or 
3016 30 16 3316 48 16 Undefined FF,, 
37 16 4616 4616 4616 7FFF i, Oi. 
46, — 46% 46 6 46 4 FFFF,, 016 


Date and Time Support Supervisor Coll ~ Code 03), 

TAXO provides a call that allows the user to obtain from the system the 
time and Julian date in binary form. The coll is the Date and Time super- 
visor call, code 0344. The coll block for the Date and Time call con- 
sists of four bytes, aligned on ao word boundary, 


Byte O - Contains the call code (03, ). 
Byte 1 - Error code returned by system, 
Bytes 2-3- Address of a five-word data buffer into which the system 


returns the time and date information. 


The following is an exomple of a supervisor call block for the Date and 
Time function: 


EVEN 
SCBJ BYTE 3 CALL CODE 
BYTE O INITIALIZES BYTE ONE TO ZERO 


BUFF DATA DATABUF ADDRESS OF THE FIVE-WORD AREA THE DATE 
* AND TIME IS TO BE WRITTEN INTO 


~ 
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The call to perform the function using the preceding block is written 
in the procedure portion of the calling task as follows: 
SVC = @)SCBJ 


t 
If the date returned were July 10, 1977, and the time were 11:59:59 A.M., 
the five words at location DATBUF would contain the following: 


YEAR DAY HOUR MINUTES SECONDS 
Word 1 Word 2 Word 3 Word 4 Word 5 
07B9 OOBF 0008 003B 003B 


3.4.4 System Log Supervisor Call - Code 21i, 


The System Log Supervisor call (code 2114) allows the user to send mes- 
sages to the system log. The supervisor call block for the System Log 
supervisor coll consists of eight bytes, aligned on a word boundary. 


Byte 0 - Contains the coll code (21, ). 

Byte 1] - Error code returned by system. 

Bytes 2-3 - Reserved, 

Bytes 4-5 - Address of o data buffer which contains the message text. 
Bytes 6-7 - Reserved, 


The following is an example of a call block to write a message ot loca- 
tion MESSII to the system log file: 


EVEN 

SCBK BYTE >21 CALL CODE 

ERRC BYTE 0 INITIALIZE BYTE ONE TO ZERO (ERROR CODE BYTE) 
DATA 0 INITIALIZE BYTES TWO AND THREE TO ZERO 

MADR DATA MESS11 MESSAGE ADDRESS 
DATA 0 


MESS11 BYTE |= MSGEND-$-1 COMPUTER MESSAGE LENGTH 
TEXT ‘THIS IS A MESSAGE' 
MSGEND EQU $ 


Within the procedure portion of the calling task, the following state- 
ment is used to issue the system log supervisor call using the preceding 
call block: 


SVC (@) SCBK 


Possible error codes returned by the system in byte 1 of the call block 
are explained in Volume VI, 


3.4.5 Retrieve System Information Supervisor Call - Code 3Fy, 


This SVC is not a privileged supervisor call and is primorily only use- 

ful to low-level tasks, The SVC is used in obtaining various types of 
system dota but cannot be used to modify the data, The normal call block 
is 16 bytes long, but a shorter call block exists for retrieving only a 
single word. Both forms of the call block must begin on a word boundary, 

A task that uses this SVC may be incompatible with future versions of TAXO, 
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The format of the normal call block is as follows: 


BYTE 

ee 
os 
i sea eee 
io ee 
Se 
ee 


BUFFER ADDRESS 
RESERVED (#0) 


The following is the format of the short call block: 


BYTE 

e ee enema 
Src a 
ee 
Se ed 
Ao er 


WORD RETURNED 
NOT USED 
NOT USED 
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Byte 


6-7 


Byte 
8-9 


10-11 


12-13 


14-15 


NOTE 
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Description 
Contains the call code (3F,, ). 
Error code returned py TAXO: 


O = No error 

1 = Invalid data type 

2 = Invalid index, or index out of range 
3 = Offset out of range 


Data type requested: 
1 = Physical Device Table (PDT) 
2 = Overlay table 


3 = Addressable memory 
Flags: 
Bit 0 = When set to 1, indicates using 


short form of call block. 
Bits 1-7= Not used, Set to zero. 


Index do desired structure. From 1 to n, 
where n is the number of structures. 


Offset into dato structure (in even number 
of bytes), From 0 to 1-1, where 1 is the 
length of the structure, 


The contents of bytes 8-15 depend on whether this is a normal 


or short version of the call block, as determined by bit 0 of 


byte 3, 


Description 


Normal call block: 
Length of return buffer (in bytes). 


Short call block: 
Not used, : 


Normal call block: 
Actual length returned, 


Short coll block: 
Word returned, 


Normal call block: 
Buffer address (on word boundary). 


Short call block: 
Not used. 


Normal call block: 
Reserved, Initialize to zero. 


Short call block: 
Not used. 


renee 
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The index, bytes 4-5, is used for linked data structures such as PDTs 
and indicates which one to retrieve. The offset, bytes 6-7, determines 
the first word of the structure to retrieve, and the buffer length, 
bytes 10-11, determines how many words ore retrieved. For the short 
form of the call block, no buffer is needed, as only one word is re- 
trieved and returned in bytes 10-11 of the call block. 


The following code is an example of the normal coll block of the Re- 
trieve System Information SVC: 


EVEN 
RSISCB BYTE >3F SVC CODE 
BYTE >00 ERROR CODE. 
BYTE 1 RETRIEVE A PDT. 
BYTE >00 FLAGS (NORMAL CALL BLOCK), 
DATA 5 RETRIEVE THE 5TH PDT IN THE 
DATA 0 CHAIN STARTING WITH THE FIRST 
DATA  BUFLEN WORD FOR A LENGTH OF BUFLEN, 
DATA 0 ACTUAL LENGTH RETURNED, 
DATA  BUFADR BUFFER ADDRESS, 
DATA 0 RESERVED. 
+ 
BUFADR BSS 72 BUFFER FOR RETURNED PDT 


BUFLEN EQU $-BUF ADR LENGTH OF BUFFER 


SVC @RSISCB RETRIEVE SYSTEM INFORMATION 


The following code is an example using the short form of the call block: 


EVEN 
SHORT BYTE >3F SVC CODE. 
BYTE >00 ERROR CODE, 
BYTE 2 GET DATA FROM OVERLAY TABLE, 
BYTE >80 FLAGS (SHORT CALL BLOCK). 
DATA 1 INDEX (ONLY 1 OVERLAY TABLE). 
DATA >IC OFFSET INTO OVERLAY TABLE, 
DATA 0O IGNORED FOR SHORT CALL BLOCK, 
LDTADR DATA O WORD RETURNED HERE, 
DATA 0O IGNORED FOR SHORT CALL BLOCK, 
DATA 0O IGNORED FOR SHORT CALL BLOCK. 
SVC (a) SHORT RETRIEVE WORD FROM OVERLAY 
7 TABLE. 


° 
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4/\ 
SECTION 4 


DEVICE 1/0 


General 
Two types of I/0 processing are supported by TAXO; 


1, Device-independent I/0 which tends to make various I/0 devices look 
the. same to application progroms. 


‘2. Device-dependent I/0 which makes it easier to use particular device 


features which may not exist on other devices, 


All device I/0 use the some basic call structure. I/0 is done to logical 
units rather than to devices. However, for those users who wish to sacri- 
fice device independence, the I/O call block may be extended to access 
certain features peculicr to specific devices, Thus o program may use 
device independence to allow execution in a variety of physical en- 
vironments, or it may use special features (such as cursor control on 
the video terminals) to toke advantage of certain hardware capabilities. 


Within physical hardwore limitations (one cannot reod data from a line 
printer, or write data to a cord reader), the following devices may be 
considered equivalent by o program using device-independent I/0: 


Video Display Terminals 
Card Readers 
Line Printers 


This list can be expanded to include any other device that has a Device 
Service Routine implemented, 


In general, a complete I/O transaction requires the following steps: 
1, Assign a logical unit number (LUNO) to the device. 
2. Open the logical unit for 1/0, 
3. Transfer data. 
4, Close the logical unit. 
5. Release the logical unit. 
NOTE 


Physical devices must be defined to the system and a device ser- 
vice routine provided at system generation. 
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4.1.1 I/0 Device Access Strategy 


All standard TAXO 1/0 is performed to logical unit numbers instead of 
to physical devices. TAXO maintains go list of logical unit numbers that 
indicate (to TAXO) the corresponding physical device. LUNOs may be as- 
signed by operator action or by program action and may have one of three 
scopes: 


1, Global LUNOs are defined (and available) for all tasks. 


2. Station LUNOs are defined (and available) for all tasks assigned to 
a given station. 


3. Task LUNOs cre defined only for the task that defines them, 


There are two strategies for resource allocation implemented by selecting 
the scope of LUNO assignment: 


A. GLOBAL OR STATION LOCAL LUNO STRATEGY 


The Global LUNO strategy isolates resource allocation from program 
execution, For example, an analog to digital (A/D) converter might 
be used as a process monitor. There may be many programs which in- 
teract in the process and it would be convenient to assign a single 
global LUNO to the A/D converter. In this case, all the programs 
associated with this process monitor could access the A/D data 
without making provision in each program for resource allocation. 


Station local LUNOs may be used to isolate resource allocation from 
program execution in a similar manner. Extending the example given 
above, suppose that there are several operator stations, each with 
an operator terminal and A/D converter. The strategy is similer to 
the global LUNO strategy; each station may have severol programs 
which access the A/D converter. Thus, it would be convenient to as- 
sign a single station local LUNO to the A/D converter. In this cose, 
any program entered at an operator station could access the A/D 
converter assigned to the station without program provision for re- 
source allocation, In addition, if the station LUNO numbers ore the 
some for each station, a particular progrom may be replicated for 
every station without reprogramming. 


B, TASK LOCAL LUNO STRATEGY 


This strategy binds resource allocation to task execution, This stro- 
tegy is appropriate for tasks which could have I/0 access to several 
different devices or files, For exomple, a language processor usually 
cllows the user to specify, on each execution, the input source file 
(or device), the output object file (or device), and the listing 

file (or device). gu 


The task local LUNO strategy is appropriate for this example: supply 
access pathnomes to the processor, and have the processor use task 
local LUNO assignments for resource allocation. In this way several 
instances of a processor may be executing ot the same time, each 
instance having distinct 1/0 channels. 


In some applications, it may be desirable to use both strategies: a 
single progrom may use global, station local, and task local LUNOs. 


ete i AMM 
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NOTE 

Task local LUNO assignment requires more programming effort. 
However, if task local LUNOs ore appropriate for an application, 
they should be use, Inappropriate use of global or station local 
LUNOs may yield disappointing results. 


The I/0 process paths for the two strategies is illustrated in figure 
4-1, 


CAUTION 

When TAXO searches the LUNO tobles, it first looks for task local 
LUNOs, then for station local LUNOs, and finally for global LUNOs, 
Thus, a task local LUNO may mask a station lecal or global LUNO 
with the same number. The system uses global LUNOs in the range 
0016 to 21746 and D016 to FFy¢. Use of task local or station LUNOs 
in this range may produce unpredictable system performance. 
Typically, the language processors fail. If automatic LUNO gene- 
ration is specified, there will be no masking problem. 


4.1.2 LUNO Assignment 


Assign and Release LUNO calls require on extended call block as shown 
in figure 4-2. This call block is explained in detail in the file 1/0 
section. The call block description supplied in table 4-1 applies spe- 
cifically to devicel/0, 


NOTE 

There ore certain fields of the I/0 coll block which contain 
pointers to extensions of the call block. These fields are not 
always required, however, it is assumed that the pointer is 
meaningful and contains a valid address. For example: an Assign 
LUNO call with a pointer to a key index file definition block 
must address memory within the task address spoce sufficient 

to cover the size of the definition block, This is true even if 
the LUNO is being assigned to some device (e.g. line printer) 
where the key index file definition block has no meaning. It is 
sufficient to place ao zero in the unused pointer field. 


4.1.3 Access Logic For Devices ‘ 


4.1.3.1 
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TAXO devices ore either file-oriented or record-oriented, All terminals 
and all disk drives (for direct disk I/0) are record-oriented devices. 
Record/file orientation is a sysgen option for other devices. As des- 
cribed in the following porographs, device orientation determines the 
programming necessary for access control. 


Record-Oriented Devices 


Record-oriented devices may be shared at the logical record level. Any 
task may occess a record-oriented device through any LUNO, with an appro- 
priate assignment scope, assigned to the device. A task accessing o re- 
cord-oriented device need not OPEN the associated LUNO. If, however, the 
progrom may be run in on environment in which it accesses a file-oriented 
device, the open call should be coded to maintain device independence. 


OPERATOR ACTION 


1, ASSIGN 
LUNO 


ASSIGN LUNO 
SCI COMMAND 


GLOBAL OR 
STATION LOCAL 
LUNO STRATEGY 


2. OPEN LUNO 


4, TRANSFER DATA 


GLOBAL OR STATION 
LOCAL. LUND STRATEGY 


} 


I/O Process Paths 


4. CLOSE LUNO | 


REIL EASE LUND 
sci COMMANL 


5. RELEASE 
LUND 


Figure 4-1, 
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PROGRAM ACTION 


ASSIGN LUNO 
sve CALL 


TASK LOCAL 
——— LUNO STRATEGY 


OPEN LUNO 
svc CALL 


VARIOUS H 
1/0 CALLS : DEVICE 
READ, WRITE... : > (NDE PENDENT 
etc CALLS 


Cr. USE LUNO 
Svc CALL 


TASK LOCAL 
Tow" LUNG STRATEGY 


RELEASE LUNO 
svc CALL 
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4.1.3.2 File-Oriented Devices 
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Only one task at a time may have access to a file-oriented device. A 
task gains access to a file-oriented device through the OPEN call, 
Before ony other task may OPEN a file-oriented device, the previous 
user must have CLOSED it. The following rules apply to file-oriented 
devices: 


1, Any number of LUNOs may be assigned to a file-oriented device, but 
only one may be open. . 


2. If an attempt is made to open a LUNO which is assigned to a file- 
oriented device which already has an open LUNO, the attempt is re- 
jected with error code >0F. If an attempt is made to open a LUNO 
which is assigned to a file-oriented device and if the LUNO is al- 
ready open to a different task, the attempt is rejected with error 
code >0OF. 


3. If an attempt is made to open a LUNO which is assigned to a file- 
oriented device and if the LUNO is already open to the some task 
making the attempt, then the OPEN is processed and no error occurs. 
This provides a convenient way to modify ottributes assigned by the 
OPEN call, 


The system will automatically close all open LUNOs when the task termi- 


nates, 
se 
oo | encore | to 
oe |_tverew rine | usemrincs | 
. 
: 
: 
: 
. 
. 
: 
" 


26 RESERVED SET TO ZERO INITIALLY 


Figure 4-2, I/0 Utility Supervisor Call Block for Assign and Release 
LUNO Calis 


Toble 4-1. 

Byte Bit 

¢) All 

1 All 

2 All 

3 

4-11 

12-13 

14,15 

16,17 

16 0 

16 1,2 
a 16 3,4 

16 5 

16 6,7 
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I/O Utility Supervisor Call Block Bit Assignments 


Meaning 
SVC code. This code is zero for all 1/0 operations. 


Status Code. This code is returned by the system 
(see ERROR MANUAL). 


Utility Opcode. This byte is set by the user to spe- 
cify the requested utility operation as follows: 


Opcode Operation 

>91 Assign LUNO to pathname. 
>93 Release LUNO assignment. 
>99 Verify Device Name, 


All other utility opcodes do not apply to device 1/0, 


LUNO, This byte specifies the LUNO to be used in the 
operation. It is supplied by the user except when the 
generate LUNO bit is set on an Assign operation. In 
this case, TAXO selects a LUNO and returns it in this 
field, 


Not used, Reserved for compatability with other calls. 
Must be zero for device I/O. 
Not Used. 


Utility Flags. These flags are used for assign LUNO 
operations. For all other utility operations these 
flags should be set appropriotely,. 


Created by Assign. This bit is set by the system but 
does not apply to device I/0. 


Must be zero for device 1/0. 


Scope of LUNO assignment. Set by the user to define 
the scope of the LUNO assignment or release. 


Code Meaning 

00 The LUNO is task local. 

01 The LUNO is terminal local. 
10 The LUNO is global. 

1 Reserved, 


Generate LUNO. Set by the user. If this flag is 1, 
TAXO automatically generates a LUNO number and returns 
it in the LUNO field (byte 3). The selection does not 
conflict with any LUNO accessible to the calling task. 
If this field is a 0, the contents of the LUNO field 
is used. This flag applies to assign LUNO operations 
only, 


Must be zero for device I/0. 
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Table 4-1, I/O Utility Supervisor Call Block Bit Assignments 


(Continued) 
Byte Bit Mecning: 
17-21 Must be zero for device I/0, 
22,23 Device Name Pointer. These two bytes contain the 


user-specified address of a device name used for 
ASSIGN LUNO operations. The device name format is 
as follows: | 


Byte O - Device name length (in bytes) = 4, 
Byte 1-4 - Device nome. 


Device nomes are assigned at system generation. 
24-27 Must be zero. 


& 4.2 Device Independent 1/0 


All user calls for TAXO services have the form: 
SVC GD ADDRES 


where ADDRES is the address of the call parometer block ond SVC is a 
symbol for XOP 15, When the first byte of the call parameter block is 
zero, the call is an I/0 call. The generol I/O parometer block for 
device-independent I/0 is indicated in figure 4-3 and explain d in 
table 4-2, 


4.2.1 Qpen (0016) 


The Open operation should be performed before any data transfer operation. 
The LUNO remains open to the task until a Close operation (Close, Close 
with EOF, or Close Unload) is performed. The system returns a device 

type in bytes 6 and 7 of the call block and if the logical record length 
is zero (byte 8), a logical record length is returned in byte 8. The 
device types and default record lengths returned are given in table 4-3, 


é For any file-oriented device, an Open operation (Open or Open Rewind) 

’ MUST be performed before any other operation, Consistent use of Open and 
Close is recommended for all files and devices; but the Open call is not 
required for record-oriented devices. 


If the device specified is a data terminal, the Open Rewind operation 
clears the terminal's input buffer. If the device specified is a printer, 
the device performs a corriage return. 


4.2.2 Close (0146) 


The Close operation, informs the system that the current I/0 sequence 

to the specified LUNO is complete. The LUNO may be subsequently reopened 

for further 1/0. If a task terminates, TAXO automatically closes all 
LUNOs opened by the task. If the LUNO is task local the LUNO Gesignment 
is also deleted at task termination. 


+ 
8 
o 
3 
oS 
a 
g 
- 


4/8 


. SVC OP CODE (00) t STATUS CODE 


DATA BUFFER ADDRESS 


LOGICAL RECORD LENGTH 


CHARACTER COUNT 


REPLY BLOCK ADORESS 


Figure 4-3, General 1/0 Supervisor Call Block 


4.2.3 Read ASCII (091¢) 
The read ASCII operation reads a record from the selected device and 
stores the characters in the specified buffer, two characters per word. 
The buffer address is specified in call block bytes 6 and 7 and the 
buffer size is specified in bytes 8 and 9, The actual number of charac- 
‘ters stored is returned in the character count, bytes 10 ond 11. If the 
length of the input record exceeds the buffer size, the remaining cho- 
racters are not available. 


The ASCII characters listed for each device in Appendix B are valid and -. 
are stored with the most significant bit set to zero. All other charac- 
ters are ignored, except as noted for the card reader. 


Table 4-2, Bit Significance of 1/0 SVC 


@ Byte Bit Meaning 
0 Specifies SVC call type. Enter 00 to indicate 1/0. 
1 Used by the system to return status code (see Error Monudl):~ 
Volume VI). 
2 OPCODE (See table 4-4 for device response) 
00 - Open — 
O01 - Close Plies ao 


02 - Close, Write EOF 
03 - Open and Rewind 
04 - Close and Unload ig 
05 - Read Device Status es 
06 - Forward Space 

07 - Backward Space if aa 
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Table 4-2, 
Byte Bit 
0 
2 
4-7 
5 
5 0 
1 
2 
3 
4 
5 
6 
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Bit Significance of 1/0 SVC (Continved) 


Meaning 


08 - Not Used 

09 - Read ASCII 
OA = Read Direct 
OB - Write ASCII 
OC - Write Direct 
OD - Write EOF 
OE - Rewind 

OF -- Unload 


LUNO (Logical Unit Number) 
System Flogs (set and reset by TAXO). 


Busy. l=busy O=done. Do not modify data buffer or call 
block when busy. 


Error. l=error, O=No error. 
EOF, l=end of file detected on input call. 


Event character flag. Set to | if an input operation 
from a terminal was terminated by on event character, 
See porograph 4.4.2 for a description of event cha- 
racters, 


Unused. 


User flags. The user sets these flags to indicate the 
following to the system: 


Initiate. When this flag is set, the system returns 
control to the calling task without waiting for .1/0 
completion. 


Ovtput with Reply. See reply block (below). When set, 
this flag indicates two operations instead of one. 
For write operation, the reply flag indicates write 
followed by read. This flog applies only to write 
operations to terminal devices, 


Reserved - Set to zero. 
Reserved - Set to zero. 


Use extended call block for terminal device. 


Pee ay 


Table 4-2. 
Byte Bit 

7 
6,7 


@ 8,9 


10,11 


12,13 


4/10 


Bit Significance of I/0 SVC (Continued) 


Meaning 


$ 
Blank Adjustment and Event Character Flag. This flag 
controls the blank adjustment option on READ or WRITE 
operations and the event character option on OPEN 
operations. 


Blank Adjustment. 


If this bit is set on read operations from CRU devices 
with variable length records and the input logicol re- 
cord is shorter than the specified input buffer 

(bytes 8, 9) then the buffer is filled with blanks 
(20) from the end of the input logical record to the 
end of the buffer. The valve returned as the charac- 
ter count (bytes 10, 11) is equal to the adjusted re- 
cord length including the blanks. In no case will the 
adjusted record length be less than the systems device 
buffer size, 


On write operations to CRU devices with varioble length 
logical records all trailing blonks in the output buf- 
fer are deleted before the output is performed. The 
output character count specified in bytes 10, 11 is 

not modified. 


Event Character Option, 


If this bit is set on an open operation to a terminal, 
then the event character option is selected for all 
subsequent read operations to that terminal. See po- 
ragraph 4.4.2 for a description of event character 
support, 


Data Buffer Address (Must be even). 


Logical Record Length. Set by the calling task on in- 
put operations to specify the maximum number of cha- 
racters which may be stored in the input buffer. Not 
used for output operations. If this word is zero on 
an OPEN operation for any device except Tape and Disk, 
the system returns the maximum number of characters 
which may be transferred in a single I/O request. 


Character Count. Set by the calling task on output 
to specify the number of characters to be output, 
Set by TAXO on input to specify the number of che 
racters stored in the input buffer. 


Reply Block Address. For output operations, if a reply 
is specified (Byte 5, bit 1) then this’word is the ad- 
dress of o three word block which contains the data 
buffer address, buffer length, and cheracter count to 
be used for the reply input. These three words serve 
the same function for the reply input as bytes 6-11 

do for read cally. 
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Table 4-3. 
Device Name 
'xx’ Indicates 
Device Number of Device 
DUMMY DUMY 
TELEPRINTER STxx 
LINE PRINTER LPxx 
CARD READER CRxx 
VDT STxx 
DISK DSxx 
COMMUNICATION CMxx 
MAG TAPE MT xx 
FILE USER DEFINED 
Table 4-4, 
rs 
o 
re] 
© 6 
ces 
RS 
&S3s 
Device Opcode 0 1 2 
Line Printer rer 
Card Reader rere 
Magnetic Tape Unit rorer 
Video Display Terminals ros 5 
Dummy Device rdii 


ae 


r - device Responds to opcode 
i - device Ignores opcode 
e - device returns Error code 


Device Type 
Returned 


0000 
0001 
0002 


0005 
0006 
0007 
0008 


XXFF (XX IS 


FILE TYPE 


CODE ) 


1/0 Operations 


 Close-Unload 
om Read Status 


w Open-Rewind 


wn OM 
ys 4 


Cee ee 
"4 


wes 


a 


- 


o Forward Space 


. 


rr 


bby 


~ Backward Space 


oc Unused 


Returned Device Types and Default Record Lengths 


Record Length 


Returned 


0 


>56 
>86 
>50 
>56 
0 

0 

LRL 


Device Dependent Responses To 1/0 OPCODES 


<o Read ASCII 


> Read Direct 


4 ©@ 


eo ® ® e® @ 
| 


4» +4 ® 


4 


of file 


@w Write ASCII 


4 


se 4 4 


O- Write Direct 
o Write EOF 


m Rewind 
m1 Unload 


4» H HH @ 


eo oe” 


ew 4 


4 


4 


»- 


4 


4 4 


4.2.3.1 


4.2.3.2 


4.2.3.3 


4.2.3.4 


4.2.4 


4.2.4.1 


4.2.4.2 
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Magnetic Tape Unit 

When the device specified is a magnetic tape unit, the Read ASCII ope- 
ration reads the current record ond tronsfers the available characters 
to the specified buffer in memory. 


Video Display Terminal 

Charocters ore transferred to the buffer until either the user enters 
a corrioge return or event character or until the field is full. Cha- 
racters can be corrected by entering the left arrow (~), which back- 
spaces the cursor, but does not delete the character. 


Cerd Reader 


When the device specified is a cord reader, the Read ASCII operation 
reads a cord and transfers the characters read to the specified buffer. 
Up to 80 characters are transferred. When more than 80 characters are 
specified, only the first 80 are read and transferred. When fewer than 
80 charccters are specified, the remaining characters on the card ore 
not read and transferred. Characters other than standord choracters for 
the cord reader (>20->5F) ore placed in the buffer as spaces, and the 
system returns an error status code when these characters ore read, The 
end-of-file record for the card reoder has o slash in the first column 
and an asterisk in the second column (/*). 


Other Devices 
The Read ASCII operation is on illegal operation for "output only” de- 


- vices like the line printer, and the system returns an error status 


code (ERROR MANUAL). 


Read Direct (0A}¢) 


The Read direct operation reads the number of characters specified and 
transfers the characters to the buffer at the address specified without 
translating ASCII characters, The number of characters read is placed 
in call block bytes 10 and 11. 


Magnetic Tape Unit 


When the device specified is a magnetic tape unit, the Read Direct ope- 
ration is the same as the Read ASCII (0934) operation, 


Card Reader 

When the device specified is the card reader, a column on the card is 
stored in a word of the buffer, The four most significant bits of the 
word are set to zero; the holes in the cord are stored as ones in the 


card column numerical order, The entire record is transferred to the 
buffer, End-of-file is undefined for a Read Direct operation. 


4.2.4.3 Video Display Terminal 


When the specified device is a VDT, the specified number of characters 
is read from the screen (not the keyboord) starting at the cursor po- 
sition. 
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4.2.4.4 


4.2.5 


4.2.5.1 


4.2.5.2 


4.2.5.3 


4.2.5.4 


4.2.6 


4.2.6.1 


4.2.6.2 


4.2.6.3 
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Other Devices 


When a Read Direct operation is attempted on the other devices, the 
system returns an error atotus code, 


Write ASCII (08j¢) 


The Write ASCII operation, code 08;¢, writes a record consisting of 
ASCII characters to the specified device from the buffer at the ad- 
dress specified in the call block. The buffer contains two characters 
per word, and the number of characters to be written is specified in 
bytes 10 and 11 of the call block. Each device recognizes the charac- 
ters listed for the device in Appendix B. Other characters are ignored. 


Magnetic Tape 


When the device specified is a magnetic tape unit, the Write ASCII. 
operation transfers data from the specified user buffer and writes 
the available characters to tape. 


Line Printer 


When the device specified is the line printer, the charocters cre also 
printed, 


Video Display Terminal 
When the device specified is the VDT, the characters ore displayed on 
the screen of the VDT. 


Other Devices 


When o Write ASCII operction is attempted on an "input only" device 
such as the card reader, the system returns an error status code (see 
ERROR MANUAL). 


Write Direct (0Cj¢) 


The Write Direct operation writes a record without performing any 
translation and writes the characters from the buffer at the address 
in bytes 6 and 7 of the call block. The number of characters to be 
written is specified in bytes 10 and 11 of the call block. 


Magnetic Tope Unit 


When the device specified is a magnetic tape unit, the Write Direct ope- 
ration is the some as the Write ASCII (08),) operation. 


Video Display Terminal 


When the specified device is ao VDT, the characters are displayed on the 
VDT screen. 


Other Devices 


When the Write direct operation is attempted on ony other device, the 
system returns an error status code (see ERROR MANUAL), 


4.2.7 
4.2.7. 1 


4.2.7.2 


4.2.7.3 
“8.2.7.4 


4.2.8 


4.2.9 
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Write EOF (0D ,) 


The Write EOF operation consists of writing the end-of-file record de- 
fined for the specified device. ; 


Line Printer 


When the device is o line printer, the operation performs a form feed 
operation. 


Video Display Terminal 
When the device is a VDT, the operation is ignored, 


Card Reader 


When the device is the card reader, the system returns an error status 
code, and no operation is performed. 


Mognetic Tape Unit 


When the device is a magnetic tape unit, the operation writes the mag- 
netic tape EOF mark, 


Rewind (0E},¢) 


The Rewind operation is specified by I/0 operation code 0Ej6. When the 
specified device is the line printer, the operation performs a form 
feed operation. When the device is a magnetic tape unit, the operation 
rewinds the tape to the load point and places the unit in the ready 
state. When the device is a VDT, the screen is erased. The Rewind ope- 
ration is ignored by other devices. 


Unload (OF 1¢) 


The Unload operation applies only to the magnetic tape unit and is ig- 
nored by all other devices. The Unload operation for the magnetic tape 
unit, the operation consists of rewinding the tape to the physical be- 
ginning in preparation for unloading the reel. 


Forward Space (061¢) 


The Forward Space operation applies only to the magnetic tape units, 
and is ignored by all other devices, The number of logical records to 
be moved is placed in bytes 10 and 11 of the coll block, and the For- 
ward Space operation moves forward the specified number of logical re- 
cords or until an end-of-file (EOF) record is encountered, If an EOF 
record is not encountered, zero is returned in bytes 10 and 11 of the 
call block. If an EOF record is encountered, the tape is positioned 
following the EOF record, the EOF flog (byte 4, bit2 of the call block) 
is set, and the number of records remaining is returned in bytes 10 
and 11 of the call block. 


4.2.11 


4.2.12 


4.2. 12.1 


4.2.12,2 


4.2.12.3 


1630/SVC/SC1/0281/e 


4/15 


Backward Space (0716) 


The Backward Space operation applies only to the magnetic tape unit, and 
is ignored by all other devices. The number of logical records to be 
moved is placed in bytes 'l0 and 11 of the call block, and the Backward 
Space operation moves in the reverse direction the specified number of 
logical records or until an end-of-file (EOF) record is encountered, 

If an EOF record is not encountered, zero is returned in bytes 10 and 

11 of the call block. If an EOF record is encountered the tape is po- 
sitioned so the next read operation encounters the EOF record, the EOF 
flag (byte 4, bit 2 of the call block) is set, and the number of re- 
cords remaining is returned in bytes 10 and 11 of the call block. 


Read Device Stotus (0546) 


The Read Device Status operation provides the user access to device 
status information on certain devices. The user must specify the buffer 
address at which the status information is to be stored in bytes 6 and 
7 of the call block and the length of the buffer in bytes 8 and 9 of 
the call block. The specified buffer must begin on a word boundary, 

The number of bytes returned by the Read Device Stotus operation will 
be indicated by bytes 10 and 11 of the call block, Bytes 10 and 11 

will be zero for all devices except those listed below. 


Magnetic Tape 


The Read Device Status operation returns two bytes of status information 
as follows for magnetic tape units, 


first byte >80 Tape unit on-line, write ring installed 
>40 Tape unit on-line, no write ring installed, 
>20 Tape unit off-line. 
second byte >80  Phase-encoded recording, 1600 bits per inch (bpi). 
00 Non-return to zero inverted (NRZI) recording, 
800 bpi. 


Video Display Terminals 


The Read Device Status operation returns four bytes of status information 
for VDTs. The first byte will contain the maximum row address of the VDT 
ond the second byte will contain the maximum column address. The third 
and fourth bytes contain the number of keyboard input characters cur- 
rently internally buffered in the character queve. 


Disk Devices 


The Read Device Status operation returns 10 bytes of status information 
for disk units. 


Bytes 0-1 - Number of words per track, 

Byte 2 - Number of sectors per track. 

Byte 3 - Number of overhead words per record. 
Bytes 4-5 


Bits 0-4 - Number of heads. 
Bits 5-15 - Number of cylinders. 


4.2.13 
4.2.14 


4.2.15 


) 4.3 


4.3.1 


4.3.2 


4/16 


Byte 6 - Number of sectors per record. 
Byte 7 ~- Number of records per track. 
Bytes 8-9 - Number of words per record. 
Close With EOF (02,,) 


The Close with EOF operation, consists of a Write EOF operation followed by 
a Close operation. 


Open Rewind (03,4) 


The Open rewind operation consists of an Open operation followed by a Rewind 
operation. It also clears the input buffer for terminal devices. 


Close Unload (04,4) 


The Close Unlood operation consists of an Unload operation followed by a 
Close operation. 


Device Dependent 1/0 


If explicitly requested, TAXO is able to defeat device independence to allow 
full utilization of all device resources for keyboard devices. Otherwise, 
TAXO I/0 is device-independent up to the limitations indicated in table 4-4 
I/O Calls to interactive terminal devices allow an extended call block which 
enables the user to specify device related functions. To specify an extended 
I/O function, a task supplies a standard I/O call block (see table 4-5) with 
user flag bit 6 in byte 5 set to one and an appended extension to the call 
block as shown in figures 4-4 and 4-5. The extension call block entries have 
the following definitions: 


Field Start Cursor Position (VDT 


This flag, when set, specifies that the start of the input or output field is 
defined in bytes 20-21 of the call block. If the Field Start flag is not set, 
the current cursor position defines the start of the field. 


On a Read ASCII call, characters are read from the field beginning at the row 
and column, specified by the Field Start field (bytes 20-21) in the call block, 


_with the number of characters to read specified in the logical record length 


field (bytes 8-9). To begin reading characters within the Field Start field, 
set the Cursor Position flag (paragraph 4.3.9), and specify the row and 
column in which to begin the read in the Cursor Position field (bytes 18-19). 
At the completion of the Read ASCII operation, the Cursor Position field is 
updated with the current cursor address. 


If the 1/0 call is not Read ASCII, the cursor is moved to the start of the 
field at the beginning of the I/0 operation. The Cursor Position field is 
only used on Read ASCII I/O calls. 


Intensity (VDT 


This flag, when set, causes output to be done in high intensity. The CRT 
controller allows for each line up to 16 different fields in different output 
intensity. That means fields with high and low intensity. The less field is 
with one character. The first field attribute is set on column 9 and can be 
programmed with high and low intensity. If all the field attributes from one 
line are used then the remainder of the data output in this line is done in 
low intensity and an error occurs on the DTS local error line (line 24, 
column 78 and 79). 
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Blink Cursor (VOT) 


This flag, when set, causes the cursor to blink. 


Graphics (VDT) ; 


This user flag, when set to one, displays control characters (charac- 
ters >00 to >IF) as graphic characters on input and output. All cha- 
racters are treated as data; no action is taken on control characters 


request. 


Table 4-5, €xtended Call Block User Flags Definition 


Bit Definition Used in call 
Byte 14 

0 Field Start Cursor Position All 

1 Intensity - All 

2 Blink Cursor All 

3 Graphics Read/Write 

4 8-Bit ASCII* Direct (Read/Write) 

5 Carriage Control* Read 

6 Beep Read/Write 

7 Right Boundary Read 
Byte 15 

0 Cursor Position Read 

1 Fill Character Read 

2 Initialize Field Read 

3 Return on Termination- Read 

Character 

4 Do Not Echo* Read 

5 reserved Read 

6 reserved Read 

7 Warning Beep Read 

8-Bit ASCII 


This user flag, when set to one, allows the user to specify Bit 0 of 

each character in the output buffer. Bit 0 is the intensity control bit 
for VDTs. By specifying Bit 0 a user can specify the intensity of each 
character output on ao Write Direct operation. (Bit 9 = J = high intensity). 


Carriage Control 


This user flag, when set, causes task edit characters entered on an input 
fall to terminate the operation and to be returned in the Event Byte field 
of the call block. If the Carriage Control flag is not set, then task edit 
characters ore ignored. 


Beep (VDT) is ignored 


4.3.8 Right Boundary (VOT) 


This user flag, when set, limits character deletion or insertion to the 
present row when the field extends past the present row. 
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4.3.9 Cursor Position (VDT) 


4.3.10 


The user flag, when set, positions the cursor to the row and column 
specified in the Current Cursor Position field in bytes 18 and 19 of 
the call block on a Read ASCII call. This allows input of characters 
already displayed beginning at the field start position up to and in- 
cluding the character before the cursor. The actual number of charac- 
ters input is controlled by the count in the Logical Record length 
field in bytes 8 and 9 of the call block, At the completion of input 
or output operation, the Current Cursor Position field is updated 
with the current cursor address. Cursor positions begin at row 0, 


column 0. 


Fill Character (VDT 


This flag, when set, specifies that the character in byte 16 of the 
call block is to be used as a fill character whenever a character 
editing response needs a fill character, When this flag is not set, o 
blank will be used as the fill character. 


SVC OP CODE STATUS COOE 
| orcooe =| un 
pie beeebeiiee 2) Sa 
DATA BUFFER ADURESS 
LOGICAL RECORD LENGTH 
CHARACTER COUNT 
CHARACTER VALIDATION TABLE ADORESS OR 
REPLY BLOCK ADDRESS (OPTIONAL) 
EXTENDED USER FLAGS 
FILL CHARACTER EVENT BYTE 
CURSOR POSITION 
RO COLUMN 


w 
FIELO BEGINNING DEFINITION 
ROW COLUMN 


STANDARD 
CALL BLOCK 


CALL BLOCK 
EXTENSION 


Figure 4-4, Extended I/0 Call Block 


4.3.11 Initiclize Field (VDT) 


This user flag, when clear, initializes the input field with the fill 
character and positions the cursor to the start of the field. 
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Return on Termination Character (VDT) 
This user flag, when set, requires o field termination choracter to be 
input before returning to the calling task. Once the input field is full, 
additional charocters are accepted but not displayed or returned to the 
celling task. When the flag is clear, input terminates when a field 
termination character is entered or when the field is full. 
The cursor will advance one position past the end of a field if a field 
terminator is required. Field termination or error correction charocters 
may be entered to the VOT. If the last position of the field is the last 
position of the row, the cursor is positioned to the next line. If the 
row is the last row of the screen, the cursor is turned off, giving the 
impression that it has advanced off of the screen. 
Do not Echo 
This bit, when set, causes output from field begin to field end with the 
DTS not visible mode. 
Warning Be vor 
This flag, when set, causes an audible sound dhenwes functions ore 
attempted such as left arrow when the cursor is at column zero, delete 
character when there are no characters to delete, or insert character when 
there is no room to insert characters. When this flag is not set characters 
are allowed to be lost off the end of the field. 
Terminal Output 
The Stop key halts all terminol operctions until the next key is entered. 
If the next key entered is the RETURN key, output is oborted. If the next 
key entered is the exclamation point (!), SCI is bid. If the next key 
entered is the CMD key, the task is aborted. If the next key entered is 
other than the RETURN, exclamation point, or CMD key, terminal operations 
are resumed. 
Terminal Default Conditions 
I/O to a terminal may use either the general I/O or the extended 1/0 call 
block. When using the general I/0 call block (bit 6 of byte 5 set to zero), 
the default conditions apply. The default conditions are those that would 
result if the extended I/O call block were used with all bits of the 
extended user flag set~to zero. 

en Call 
The whole’ scteen will be erased. 
Output Call 


When all bits, in byte 14, of the extended user flag are set to zero or the 

general 1/0 call block is used for an Output call, the following conditions 

apply: 

1. Output is displayed at the current position. 

2. Characters are displayed at low intensity. 

3. A carrioge return (70D) positions the cursor at column one of the 
current row. 

4. A line feed (>0A) moves the contents of the display up one of the 
positions the cursor at column one of the current row. 
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Input Call 


The cursor is only visible by input calls. For all other calls the cursor 
is not visible. 

When all bits, in byte 14, of the éxtended user flag are set to zero or 
the general I/O call block is used for an Input call, the following 
conditions apply: 


1. Characters entered are displayed at the current cursor position. 
2. Characters entered are displayed at low intensity. 
3. Entering ao return positions the cursor at column one of the current row. 


Key Types (see 4.6 
TAXO separates the keys on a keyboard into four types: 


1. Data 

2. Event 

3. System Edit 
4. Task Edit 


Data Keys 

Data keys include the printable characters and do not include the control 
characters (ASCII 00 - IF and 7F). When data keys are struck, the cor- 
responding ASCII code is placed in the data buffer. 


Event keys on the VDT include the keys CONTR+A; CONTR+B;......CONTR+H, CMD, 
PRINT, CONTROL ‘1', CONTROL ‘2°, CONTROL ‘4°, CONTROL '5', CONTROL '6', and 
CONTROL ‘7°. The event keys are input to the data buffer along with data 

and edit keys in chronological order. Entering an event key terminates input 
and causes immediate return to the calling routine if the event option is 
specified in the last OPEN call, otherwise the event key is ignored. If 
input is not in progress, the next executed terminal input is terminated by ~ 
the event character. No data is lost. There are two ways to access event 
characters: 


1. If no input is in progress, or if the I/O call in use is a device- 
independent call, then event characters may be accessed using the 
Get EVENT Character supervisor call. 


2. If an extended input call is in progress, the event character is re- 
turned in byte 17 of the extension block. 


Event choracters are maintained seporately from data characters and may 
be used os task programmable keys for special applications. A task can 
obtain event characters with o Get Event Key supervisor call or with 

an input call which uses on extended call block on keyboards appended 
with the event character option specified. 
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4.4.2.1 Get Event Key Supervisor Call 


The Get Event Key Supervisor call block is four bytes in length and 
returns a single event choracter unless there are no event choracters 
in the character buffer. A task specifies the character buffer by sta- 
tion ID (SVC code >30) or by LUNO (SVC Code >39). Station ID or LUNO 
is specified in byte 3, The event charocter is returned in byte 2. The 
equal bit in the status register is set on when an event character is 
returned, otherwise it is turned off. 


00 SVC CODE -~>30/>39 STATUS 
02 EVENT CHARACTER STATION ID/LUNO 


>30 is a call by station while >39 is a call by LUNO 
The status codes returned are: 


O - Event Character 

1 = Buffer Empty 

2 - Station Not Available 

3 - LUNO Not Assigned (CALL >39), or Illegal Station Number 
(CALL >30 


4.4.2.2 Event Key Input 


A task gains access to event keys by specifying the Event Key option, 
user flag 7 (byte 5 bit 7 of the call block), on an open call to that 
device. The task may then obtain event keys from the input buffer using 
the event key SVC or with on input call using an extended call block. 
The extended call block format is specified with user flag 6 (byte 5 
bit 6 of the call block). 


With the Event Key option, event keys act as field terminators on input 
calls. The event key flag in the system flags field (byte 4 bit 3 of the 
call block) is set to one when an event key terminates on input opera- 
tion. The event key is returned in byte 17 if an extended coll block 

was specified; otherwise the user must issue an event key SVC to ob- 
tain the event key. 


CAUTION 

Any tosk may occess the chorocter input buffer by performing I/0 
to the some LUNO. Therefore, existing programs might fail if 
cnother task removes the event key from the character buffer. 
The user must be especiolly careful when the task is performing 
1/0 to a device to which SCI is also performing 1/0. Both the 
user and SCI may be corrupted. 


a ec 


.s 


4.4.2.3 


4.4.3 


4/22 


Task Programmable Event Keys 


The event keys which may be programmed from the task level are the fol- 


lowing: 
t 


CONTR+A >81 
CONTR+B >82 
CONTR+C >83 
CONTR+D >84 
CONTR+E >85 
CONTR+F >86 
CONTROL '4° >9C 
CONTROL ‘5° >9D 
CONTROL '6° >9E 
CONTROL '7' >OF 
CONTROL ‘1° >80 
CONTROL '2' >9A 
CONTR+G >96 
CONTR+H >97 
Command >98 
PRINT >99 


System And Task Edit Keys 

System edit keys include cursor and display control keys including ERASE 
FIELD, LEFT ARROW, TAB, SKIP, HOME, RIGHT FIELD/RETURN, ERASE INPUT, DELETE 
CHAR, INSERT CHAR, RIGHT ARROW, and RESET. These keys have special meanings 
for TAXO and entering them usually affects the display. Many of these keys 
are also task edit keys: the code for these keys is returned to the calling 
task for further processing. Two of the system edit keys have special 
effects other than screen editing: 


1. The Field Release key serves as an End-Of-Record for input. 
2. The Stop implements a HOLD function as follows: 


Pressing the Stop key temporarily halts terminal output. Sub- 
sequent action depends on the next key entered, as follows: 


If the exclamation (!) key is pressed, SCI is activated and the output 
continues. If the CMD key is pressed, the current task is oborted. If 
any other key is pressed, the output resumes. 


Task edit keys include TAB, DOWN ARROW, SKIP, HOME, RIGHT FIELD, ERASE 
INPUT, INSERT LINE, SEND, LEFT FIELD, and UP ARROW. These keys generate 
codes returned to the calling task under the following conditions: 


1, If no terminal input is in progress, or if standard device independent 
I/O is in progress, no code is returned except that Field Release key 
and SEND KEY constitute end-of-record and end-of-file characters, 

_ Fespectively. 

2. If an extended input operation is in progress, and if bit 5 of byte 14 
is set to one then these charocters ore treated as event choracters and 
returned in byte 17 of the extended call. 


NOTE 
Several of the indicated keys are both task edit keys and system edit 
keys. The effect of the system and task edit keys are described in 


the following paragraphs. 
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ERASE FIELD, This key fills the field with the fill character and po- 
sitions the cursor at the beginning of the field. 


ERASE INPUT. This key acts the some as Erase field but returns to the 
calling task with the chatacter code >8E in byte 17 of the extended 
call block, 


HOME. This key positions the cursor at the beginning of the field and 
‘returns to the calling task with the charocter code >8C in byte 17: of 
the extended call block. ; 


SKIP, This key fills the field from the present cursor position to the 
end of the field with the fill character, ploces the cursor one charac- 
ter position beyond the field, and returns to the calling task with 
the character code >8B in byte 17 of the extended call block. 


DELETE CHARACTER, This key deletes the input character under the cur- 
sor, moves all characters within the field to the right of the cursor 
left one character position, replaces the last character position of 
the field with the designated fill character, and leaves the cursor at 
its position prior to the keystroke. If there are no choracters from 
the present cursor position to the right end of the field, this key 
gives a warning beep, if the warning beep bit is set. 


TAB, This key accepts all characters from the present cursor position 
to the first fill charocter (if other than a blenk) or to the end of 
the field, leaves the cursor one character position past the end of 
the field, and returns to the calling task with the character code >89 
in byte 17 of the extended call block. 


INSERT CHARACTER, If the character under the cursor is the fill charac- 
ter and not a blank, this key gives a warning beep and does nothing. 
Otherwise, it sets the input mode to insert characters, and gives a 
warning beep when an inserted character couses characters to be lost 
on the right end of the field (if the warning beep bit is set), but 
lets the characters be lost off the end of the line if the warning beep 
bit is not set (any keystroke not entering dota will change the input 
mode back to the noninsert mode). 


LEFT FIELD (Field). This key positions the cursor to the beginning 
of the field and returns to the calling task with the character code 
>94 in byte 17 of the extended call bieck. 


LEFT ARROW (—). If the cursor is at the beginning of the field, this 
key gives a warning beep if the warning beep flog is set. Otherwise, it 
moves the cursor left one chorocter position, 


UP ARROW (1). This key returns to the calling task with the character 
code >95 in byte 17 of the extended call block. 


RIGHT ARROW (-—). This key leaves the charocter under the cursor intact, 

moves the cursor right one character position, and, if the cursor moves 

beyond the end of the field, returns to the calling task (if designated 

by the extended call). This key gives a warning beep on keystrokes which 
would cause the cursor to move beyond the end of the field (if the war- 

ning beep flag is set). 
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DOWN ARROW ( ). This key returns to the calling task with the character 
code 8A in byte 17 of the extended call block. 
SEND. Field Release. Same as TAB. 


t 


4.5 Other 1/0 Related Calls 


In addition to the 1/0 calls specified by supervisor call code 0, TAXO 
also supports the I/0 related calls discussed in the following para- 
graphs. 


4.5.1 Wait For 1/0 (01}¢) 


4.5.2 


The Wait for 1/0 supervisor call places the calling task in suspension 
pending completion of a specified I/0 operation, The supervisor coll 
block contains four bytes, aligned on a word boundary. 


Byte 0 - Contains the call code (01},). 


Byte 1 - Error code returned by the system. The only error code 
returned is a 041,, indicating an illegal SVC, Initiolize 
to zero. 


Bytes 2-3 - The address of the call block which defines the I/0 ope- 
rotion plus 2, 


When the specified operation is not in progress, the function returns 
control to the calling task immediately, 


The following exomple shows coding for a supervisor coll block for a 
Woit for I/0 call: 


EVEN 
SCBS BYTE 1, O _ Suspend the calling task pending completion of 
DATA BLOCK5+2 the I/0 operation defined in the call block at 
location BLOCK5, 


Wait On Multiple Initiote I/O Supervisor Coll (Code 3616) 


This call allows a task to guspend until any one of several initiate 
1/0 calls pending for the given program is complete, When the task 
is unsuspended, it must examine the busy flag in each call block to 
determine which I/0 operation has completed. 


+0 SVC CODE = 36,;, ERROR CODE 
+2 RESERVED (=0) 


Byte Description 

6) SVC code which defines this function 

1 Error or status code returned by system 
2 Reserved, Set to 0. 


If no I/0 is outstanding for the requesting tosk, the system returns 
control immediately. A status code indicating the conditions of return 
is provided. These status codes are discussed in ERROR MANUAL, 
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4.5.3 Abort 1/0 On Specified LUNO Supervisor Call (Code Fy¢) 


The Abort I/0 supervisor call, code F16, terminates I/0 operations on 
the specified device, The calling task is suspended during execution 

of the Abort I/0 supervisor call. If the device is file-oriented, it is 
closed, If the device is busy, the system sets the error flog (1/0 call) 
for the current operation. No device operation is performed, and the 
medium remains positioned as the last 1/0 operation left it. The super- 
visor call block consists of two bytes, and need not be aligned on a 
word boundary, Byte 0 contains the code, and byte 1 contains the LUNO 
assigned to the device, 


The following example shows the coding for a supervisor call block for 
an Abort 1/0 call: 


SCBA BYTE >F, >11 Abort I/O to the device to which LUNO 11y¢ is 
assigned, 


NOTE 
This supervisor call is available only to privileged tasks. 
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5 FILE 1/0 


5.1 Introduction 


TAXO provides disk file I/O support for application and system programs. 
Disk file I/O is performed through the same SVC call mechanism used to 
perform I/0 to devices. Assembly languoge programs must directly in- 
corporate the supervisor call mechanism to perform 1/0, The mechanism 

is transparent to a high level language program since the language 
translator generates the appropriate supervisor calls. This section des- 
cribes the file structures available to the assembly language progromer, 
how to create and delete files at run time, and how to perform file I/0, 


TAXO supports three different organization for files: 
@ Sequential files 
e Relative record files 


e e Key indexed files. 


5.2 File Organization and Use 


The following paragraphs discuss the file organization and use for each 
of the three file types. 


5.2.1 Sequentiol Files 


Sequential files are variable record length files whose records are al- 
ways accessed “serially” (i,e., record 0 must be accessed first, record 
1 must be occessed next, etc.). Sequential files resemble files on mag- 
netic tape. Example of sequential file use include the following: : 


e As an input file of card images - if a logical record length of 80 is 
specified, the sequential file can "look" just like a card reader to 
the program reading the file. 


e As an output file - to look just like the line printer. 


e To hold listing files from such TAXO processes as the assembler and 
: the link editor. (This is a recommended programming practice with 
é TAXO, Assembly listings should not be printed directly. Rather, they 
should be written to a sequential file. This saves time since the 
at speed of the assembler is limited by the speed of the printer. If 
needed, the list file can be examined and printed. ) 


5.2.2 Relotive Record Files 


Relative record files are sometimes called random access files because, 
unlike sequential files, records may be accessed in arbitrary order. 
Each record in a relative record file is addressed by a unique record 
number. To access record#i, the value i is pleced in the oppropricte 
field of the I/O Supervisor call block. The range of record numbers is 
from O to one less than the number of records in the file. The upper 
limit on the number of records in a relative record file is 274, Records 
in a relative record file are fixed length and the length must be speci- 
fied at file creation. 


Relative record files are useful when eoch record in the file can be as- 
sociated with a unique value ranging from 0 to some n; for example, in an 
inventory file, item number is appropriote for record number, In this 
case, to obtain information about item number i, access record #i. 
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TAXO converts the record number to a physical address on the disk 
(track and sector) ond can directly access any record in one disk 
access. On the other hand, relative record files may be accessed se- 
quentially (by placing a starting value in the record number field of 
the 1/0 call block). TAXO automaticdlly increments the record number 
after each read or write. 


Relative record files may be blocked or unblocked, It is often desi- 
rable to block relative record files for faster processing. Actual 
disk transfers of buffers may be deferred for blocked relative record 
files, Once a buffer for a block is allocated in memory ond the block 
read from disk, all reads from that block reference the memory buffer 
for the block. Unless the "immediate write" option has been selected, 
information directed to records already in memory is not written back 
to disk until TAXO requires the memory space allocated to the blocking 
buffer or until the file is closed, 


There are three special types of relative record files which provide 
special interface mechanism for TAXO. These special types are directory 
files, program files, and image files. 


5.2.3 Key Indexed Files 


A key indexed file allows random access to its records through o "key", 
which is a character string in o fixed position within the file's re- 
cords, From 1 to 14 separate keys may be specified. For example, the 
records in an employee file might be accessed by employee ID, employee 
name, ond employee sociol security number. 


In addition to random access, key indexed files have these features: 
e Records may be accessed sequentially in the sort order. of any key. 


e At file creation, a key may be given the attribute of allowing "du- 
plicates", i.e., of allowing two or more records in the file with 
the seme value for this key. 


e Also ot file creotion, o key may be given the attribute of being 
"modifiable", This means that when a record is being rewritten, the 
key value may chonge. Also, o key value may be missing in the record 
but added later on a rewrite, This attribute may not be assigned to 
the first (primary) key. 


e Keys may overlap. . 

e A key may be up to 100 contiguous characters in length. 

e Records may be of variable length and may change in size on o rewrite. 
e Positioning on partial keys is allowed, 

e Records are automatically blonk suppressed. 

e Record level locking is supported. 


e@ The file may grow in size. 


1630/svc/sc1/0281/e 


5/3 


e Integrity of the files is maintained through pre-image logging of 
modified blocks. Before ao record is modified on disk, it is copied 
to a backup area in the file overhead area. System crashes, power 
failures, and other cgtastrophies result in, at worst, loss of the 
last I/0 operation. 


e@ A key indexed file may not contain records of odd or zero length. 


5.3 File Management Overview 


5.3.1 


Terminology 


A file consists of a collection of data groupings called logical records, 
This division of the file into logical records does not necessarily cor- 
respond to the physical division of data on the disk, Thus, there are 
two types of records: logical records, the data grouping of a file as 
seen by a (user) program, ond physical records or the buffers physically 
transferred between memory and disk. 


The length of the logical records within a file may be constant or the 
logical record length may vary over the records in the file, depending 
on the file type. 


For relative record files, logical records are fixed length. This makes 
it possible for the system to calculate the physical position of any 
logical record written on disk relative to the beginning of the file. 
Essentially, the location on the disk is given by the calculation: 


logical record position = file position + (record number * record length). 


Sequentially files and key indexed files allow variable length logical 
records, The record length for key indexed files is alwoys an even num- 
ber of bytes. Sequential file logical records may be any number of bytes, 
including zero. 


When a file is created, the user must specify the isehéai record size. 
For relative record files, the size must be exact, For sequential and 
key indexed files, the record size is used to calculate the amount of 
disk space to be initially allocated to the file and should be an esti- 
mate of the average logical record size. The more accurate the estimote, 
the better the utilization of disk space, 


The physical record length is specified at file creation and is always 
constant for the entire file, 


It is often advantageous to store multiple logical records in a physi- 
cal record, This is called blocking. | 


Since disk transfer and latency times are relatively long, it is often 
best to choose physical records large enough to include several logical 
records, When a task first issues a read request, TAXO actually reads 

an entire physical record into memory. The physical record is stored 

in an area of memory called a blocking buffer, and only that part which 
corresponds to the requested logical record is passed to the requesting 
task, Subsequent read and write requests to a physical record in memory 
do not cause immediate disk access but instead reference the record 
image in memory. TAXO keeps an accessed physical record (which usually 
contains several logical records) in memory until the memory crea is 
needed for other purposes. The blocking of logical records into physical 
record images, together with the deferred write capabilities may substan- 
tially improve system throughput, especially for sequential files. 


5.3.2 


5.3.3 


5.3.3.1 
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Sequential and multi-key indexed files support variable length records. 
Be sure that the physical record size (specified at file creation) is 
large enough to accommodate three blank suppressed records plus 18 
bytes (for overhead) in a key indexed file. Since TAXO will split 1lo- 
gical records into two or more physical records in a sequential file, 
the physical record size may (but should not for efficiency) be smaller 
than the largest logical record, TAXO will assign o default physical 
record size, based on file type, when files are created. 


File Compression 


Blank suppression and blank adjustment are two methods of saving disk 
space within a file by storing data in a more compact form. These 
methods apply only to key indexed and sequential files. Blank suppres- 
sion always occurs on key indexed files, Otherwise, these features are 
optional, 


Blank suppression replaces strings of blanks by a count of blanks when 
writing to disk and restores the blank string when reading from disk. 
In operation, blank suppression is transparent to the user, It is ge- 
nerally advantageous to specify blonk suppression for files such as: 


e Source files, 

e Listing files, 

@ Text files 

since these files usually contain many blanks. 


On the other hand, while no harm results, it is less advantageous to 
use blank suppression for files such as: 


e Binary files (not ASCII data) and 

e Relocatable ASCII coded object files 

since there are very few blanks to suppress. 

A blank suppressed record with no blanks is 1 word longer. 


The second method (blank adjustment) is applicable to sequential files 
and key indexed files (and I/0 devices with voriable record lengths). 
Blank adjustment trucates trailing blanks on output and restore them on 
input. 


File and Record Protection Features 


TAXO provides several features for protecting files from progrom flaws 
which might otherwise destroy valuable data, 


Delete and Write Protection 


Two of the filé protection features provided by TAXO are delete and write 
protection. These file attributes are modifiable by standard 1/0 calls, 
Files ore initially created without protection. A subsequent I/0 call 
must be made to invoke protection, 


An attempt to write to or delete a file with write protection will fail 
and return an error code, An attempt to delete a file with delete protec- 
tion will fail and return aon error code, Write protection includes auto- 
matic delete protection. These protective attributes are not intended for 
file security (there ore nonprivileged supervisor colls to remove write 
and delete protection). Instead, they provide protection aqainst proaram 
flaws which might otherwise destroy valuable data. 


5.3.3.2 


5.3.3.3 
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Record Locking 


TAXO provides record locking for files. Basically, this means that al- 
though access to a given file may be shored between several users, in- 
dividual records may be locked to provide exclusive (single user) read 
and write access, This is not a security feature since any file user 
can unlock a locked record; however, this feature is quite useful in 
insuring that record updates occur one at a time. For example, inven- 
tory files might be accessible from several terminals. Record locking 
can prevent the situation wherein two or more users attempt to update 
a record simultaneously, causing an undetected loss of one of the up- 
dates, 


Example: 
Without Record Lock With Record Lock 
1. User A read a record, 1, User A reads a record ond locks it 


by setting the Lock/Unlocked flag 
(byte 5, bit 5) in the call block. 


2. User B reads the same record. 2. User B attempts to read the same re- 
cord but, finding the record locked, 
waits for user A to unlock the re- 
cord before proceeding. 


3. User A updates his copy of 3. User A updates the record, writes it 
the record and writes the back to disk which unlocks it if the 
updates record to disk, Lock/Unlock flog is set. 


4, User B updates his copy of 4, User B reads the record and locks it. 
the record and writes the 5 


updates record to disk, User B updates the record, writes it 


back to disk and unlocks it. 


Final Result: User B's update Final Result: Both updates are now in- 
is incorporated in the finol cluded in the record, 

record, but User A's updote is 

not included, : 


File Access Privileges 

In order to assist intertask I/O synchronization, TAXO supports several 
different access modes. These modes define the relationship between lo- 
gical units and files and disallow conflicting accesses by other logical 
units, There ore four access modes applicable to key indexed, sequential 
and relative record files and three access modes applicable to sequential 
files. Enforcement of file access privileges is through the OPEN, OPEN 
REWIND, or OPEN RANDOM commands. Execution of one of these commands, 
which would cause inconsistent privileges, results in failure of the 
command. Also, the privileges may be changed (if this doesn't cause an 
inconsistency) through an I/O supervisor call. 
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Access modes for sequential, relative record and key indexed files cor- 
respond to the ANSI stondard. In the following list of access privileges, 
“write” means ony type of file alteration: 


1, Read Only - Allows calling progrpm to read but not write. 
2. Share - Allows calling program to read and write. 


3. Exclusive Write - Allows calling program to read and write, Allows 
other programs to read but not to write. 


4, Exclusive All - ‘Allows calling program to read and write. Allows no 
other access by other programs. 


Table 5-1 illustrates the allowed and forbidden combinotions of two or 
more users specifying the opening of the same file under various access 
modes. 


Table 5-1, File Access Mode Compatibility 


) Read Only Shared Exclusive Write Exclusive All 
Read Only A A A F 
Shared A A F F 
Exclusive Write A F F F 
Exclusive All F F F F 


A - Allowed combination 
F - Forbidden combination 


Bits 3 and 4 of the user flags in the I/O Supervisor call block are used 
on OPEN, OPEN REWIND, OPEN RANDOM, and MODIFY ACCESS PRIVILEGES to select 
the particular type of access privilege desired for key indexed and re- 
lative files, as follows: 


Code Meaning 

00 ~ Exelugive WRITE 
01 Exclusive ALL 
10 Shared 

11 Read Only 


@,3. Special Usage File Protection 


In order to prevent accidental use of special usage files (program, 
directory, and imoge files), two flags must be set in the call block 
used to assign LUNOs to files, These flags indicate whether the LUNO 

is being assigned to a program file, a directory, an image file, or a 
fule of no special usage (e.g. sequential, relative record, or key in- 
dexed file). If the proper flags are not set, the LUNO is not assigned 
and an error code is returned, The flags are bits 1-2 in byte 16 of the 
Assign LUNO call block (refer to paragraph 5.5.2 for more information). 
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5.3.4 Immediate Write Attribute 


When TAXO reads a record from a blocked file into memory, it remains in 
memory as long as possible, Subsequent read and write requests, read 
and write from and to the memory buffer and not the disk. Only when 
TAXO needs the memory area will the disk be accessed, Since memory is 
for faster than disk, this deferring of disk writes increases system 
throughput. However, since the disk write operation is reported com- 
plete and yet is actually deferred, any errors which occur during the 
write cycle will be unexpected and in some situations may be undetected 
by the user. For this reason, it is possible at file creation to specify, 
as o file attribute, that disk write operations not be deferred but 
occur immediately. 


The most common undetected error is disk failure. A user could update 
@ record in a block and be informed that the update has been success- 
fully completed. However, when the block is actually written to disk, 
possibly several minutes loter, an I/0 error could occur, This error is 
returned on the next service call made to the LUNO ofter the error, The 
error is returned even if the service call is not a write operation, 


Undetected errors are rare and files with the immediate write attribute 
are less efficiently processed, especially sequential files, Therefore, 
the user should reserve this attribute for sensitive files where the 
loss of small amounts of data is not permissible. Key indexed files al- 
ways have the write immediate ottribute, 


5.3.5 Temporary Files 


Usually, ao file is created and remains in existence until explicitly de- 
leted, However, temporary files may also be created and used under TAXO, 
There ore two ways to create temporory file: 


1, With an assign LUNO I/0 supervisor call with the autocreate bits and 
temporary file bit set. In this case, the file remains in existence 
only as long as the LUNO is assigned. If no name is specified, TAXO 
assigns a unique temporary file name. However, the pathname portion 
of the I/O supervisor call block may indicate the disk volume on which 
the file is to be created, The file may be explicitly named ond spe- 
cified permanent by the RENAME 1/0 supervisor call, Otherwise, it is 
deleted the first time its LUNO is released or reassigned, 


2, With o creote file with an autocreate I/O supervisor call with the 
temporary bit set and a pathname supplied. One or more LUNOs may be 
assigned to the file using the pathname, The file remains in existence 
as long as ot least one LUNO is assigned, but when the last LUNO is 
released, the file is deleted, 


5.3.6 
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Expandable Files 


At file creation (using the CREATE 1/0 supervisor call) a file may be 
given a fixed size via the primary gllocation parameter. Alternately, 
a file may be declared expandable, in which case the file is initially 
given as much space as is indicated by the primary allocation parame- 
ter. When the file grows so that it exceeds its primary allocation, 

it is augmented with secondary allocations. The secondary allocation 
parameter is the size of the first secondary allocation. Subsequent 
secondary allocations automatically and progressively increose in size 
over the previous allocation. Files will add secondary allocations up 
to a maximum of 16 allocations. If the first secondary allocation has 
size N, then the second has size 2N, the third has size 4N, ..., and 
the sixteenth secondary allocation has size 2 N=32768N, The exception 
to this algorithm is the case where the available space of the target 
disk is fragmented to the point that these fragments are allocated in 
place of the secondary allocation. This situation does not allow for 
maximum expansion of the file because of utilization of 15 secondary 
allocations which do not increase to the maximum, 


5.3.7 End-of-File (EOF) 


5.4 


5.4.1 


An EOF for a file is a logical position within the file which, when read, 
causes the EOF status bit to be set (bit 2 of the system flags). No data 
is transferred. Key indexed files have no EOF, Relative record files 
have exactly one EOF which corresponds to the record following the 
highest numbered written record, For sequential files there may be mul- 
tiple EOFs. This is because a sequential file is best conceptualized as 
a reel of magnetic tape possibly containing several files, separated by 
EOFs on the tape, Thus, a sequential file may consist of multiple dota 
sets or subfiles delimited by EOFs, EOFs are internally represented in 
sequential files by records of length 0 ond are written by the special 
write EOF operation (or by the Close with EOF operation), Note that 
writing an EOF does not prevent writing more records into the file, 


An attempt to read beyond the last EOF in a file results in an error 
code 30;,. 


File Operations 


TAXO uses the standard I/O supervisor call with associated call data 
block to effect I/O transfers and file positioning. Key indexed files 
use a different set of I/0 opcodes, Refer to subsequent paragraphs for 
further information on key indexed files. 


1/0 Call Block 


The call block for sequential and relative record files always starts on 
an even byte boundary. From 4 to 24 bytes are required depending on the 

call, Figure 5-1 illustrates the I/0 call block and Table 5-2 indicates 

the meaning of each field in the call block, 
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FOR OPEN CALI D 


Figure 5-1, Sequenticl ond Relative Record Supervisor Call Block 


Tabl 
Byte 
0 
1 


e 5-2, Bit Significance of I/0 SVC 


Bit(s) 


Meaning 
SVC code. I/0 SVC code is zero. 


Used by the system to return status code 
(see Error Manvel). 


Operation 

Open LUNO 

Close LUNO 

Close, Write EOF 

Open Rewind 

Close Unload 

Read Device Characteristics 
Forward Space Record 
Backward Spoece Record 

not used 

Read ASCII 

Read Direct 

Write ASCII 2 
Write Direct | 
Write EOF 

Rewind 

Unload 

Rewrite 

Modify Access Privileges 
Open Extend 

Unlock Record 


LUNO (Logical Unit Number), The LUNO must have been 
previously assigned to the file. 


System Flogs (set and reset by TAXO). 
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Table 5-2, Bit Significance of I/0 SVC (Continued) 


Byte  Bit(s) 
) 


3-4 


Meaning 


Busy I=busy O=done. Do not modify data buffer or 
call block when busy, 


Error l=error, O=No error. Error code returned in 
the status code (byte 1), 


EOF l=end of file record. 
Reserved, 


User flags. The user sets these flags to indicate 
the following to the system: 


Initiate, When this flag is set, the system returns 
control to the calling task without waiting for 
1/0 completion. 


Reply flag. Ignored for relative record or sequen- @ 
tial files, Applicable for key indexed files, See 

paragraph 5.4.3 for information on key indexed 

files, 


Reserved, 


Access Privileges, These bits define access privi- 
leges desired for open and Modify Access operations. 


Code Meaning 
Sequential Relative Record 

00 Exclusive Exclusive WRITE 

o1 Exclusive Exclusive ALL 

10 Read/Rewrite Shared 

1 Read Only Read Only 


"Do Not Replace" and "Lock/Unlock Flag" 


"Do Not Replace" 

On an open operation, this flag when set allows a 

open with write access privileges on a file only if & 
the file was created during the assign LUNO opero- 

tion by the autocreate operation. 


If the file existed prior to the assign, the open 
will fail. 


"Lock/Unlock" 

This flag when set locks a record on a read opera- 
tion and unlocks the record on a subsequent write 
or rewrite operation, After locking only the task 
and LUNO which locks the record may access that 
record. Locked records ore unlocked when the LUNO 
is closed, A task may unlock with the UNLOCK operc- 
tion. 


Communications Timeout. Not applicable to file 1/0. 


> 
is] 
N 
gS 
B 
S 
$ 


Table 5-2. 
Byte 


10, 11 


12, 15 
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Bit Significance of I/0 SVC (Continued) 


Meaning 
Blank Adjustment 


If this bit is set on read operations from devices 
with variable length operations and if the input 
logical record is shorter than the specified input 
buffer (bytes 8, 9), then the buffer is filled with 
blanks (>20) from the end of the input logical re- 
cord to the end of the buffer. The value returned 
os the character count (bytes 10, 11) is equal to 
the buffer length. 


On write operetions to devices with variable length 
logical records all trailing blanks in the output 
buffer are deleted before the output is performed. 
The output character count specified in bytes 10, 
11 is not modified. 


Deta Buffer Address 


The starting address, must be an even oddress, of 
the data buffer for read and write operations. 
On an OPEN operation a file code of FF is returned 
in byte 7 and a file type in byte 6 as follows: 


Type Code — File Type 
Sequential 
Relative Record 
KIF 

Directory 
Program File 
Image File 


AWM a ON — 


Record Length. Set by the calling task on input 
operotions to specify the maximum numbers of cho- 
racters which may be stored in the data buffer. 
Not used for output operations. If this word is 
zero for an OPEN operation, TAXO returns the lo- 
gical record length defined for the file, 


Character Count, Set by the calling task on output 
to specify the number of characters to be output, 
Set by TAXO on input to specify the number of cha- 
racters stored in the input buffer. 


Record Number, Set by the calling task for reloti- 
ve record files to occess a record relative to the 
first record (record 0). This field is incremented 
at the end of a successful read or write operation. 
The field is ignored for sequential files. 
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5.4.2 Sequential and Relative Record File Operations 


The following poragrophs discuss file operations for sequential and re- 
lative record files, 


5.4.2.1 Open (0044) 


The open operation assigns a task to a LUNO and enables the task to per- 
form 1/0 on the file assigned to the LUNO. If the open is successful the 
calling task has exclusive access to the LUNO whether the LUNO is global, 
station or local, The access privilege to a file granted to the task is 
the access privilege requested in bits 3, 4 of byte 5. An open must be 
performed before a task can access a file, 


The length of the call block is 12 bytes, Call block parameters appli- 
cable to an open cre: 


! 


byte 3 LUNO to be opened 
byte 5 User flags 

& * bits 3, 4 Access privileges 
bit 5 Do not replace 
byte 6 File type code 


1 - Sequential 
- Relative Record 
- Key Indexed 
- Directory 
- Progrem 

6 - Image 
byte 7 File indicator = FFi, 

or 

Device type code 

bytes 8, 9 Returns logical record length defined 
for the file if field is zero 


Om WAN 


5.4.2.2 Close (Ol) 


The close operation releases a LUNO from the calling task, The LUNO re- 
mains assigned to the file, On a close operation TAXO: 


e Unlocks any locked records associated with the LUNO, 


e Writes all modified file blocks retained in memory associated with 
the LUNO on which write was deferred, 


e Releases access privileges granted to the LUNO, 


The length of the coll block is 12 bytes, Call block parameters appli- 
cable to a close operation ore: 


byte 3 - LUNO to be closed 


5.4.2.3 Close EOF (026 ) 


The close EOF operation is the some as a write EOF followed by a close, 


5.4.2.4 Open Rewind (0316) 


The open rewind operation is the same as an open followed by o rewind, 


8.4.2.5 Close Unload (0414) 


The close unload operation is the same as a close. 
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5.4.2.6 Read File Characteristics (05y6) 
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The Read File Characteristics operation provides the user access to the 
file characteristics information. The user must specify the buffer ad- 
dress at which file characteristics ore stored in bytes 6 and 7 of the 
call block and the length of the buffer in bytes 8 and 9 of the call 
block. The specified buffer must begin on a word boundary. The number 
of bytes returned by the Read File Characteristics operation will be 
indicated by bytes 10 and 11 of the call block. 


The number of bytes returned for the different file types are: 


Sequential 10 bytes 
Relative record 10 bytes 
Program 12 bytes 
Key indexed 12 + 4N where N = number of keys and n < 14 


The characteristics returned are described in table 5-3, 


Table 5-3, Information Returned for Read File Characteristics Operation 


Byte Contents 

0-1 File Attribute Flags 
Bits 
0-1 File Usage Flags 


00 No Special Usage 
Ol Directory 
10 Program File 
11 Image 
2-3 Data Format 
00 Not Blank Suppressed 
Ol Blank Suppressed 
10 Reserved 
11 Reserved 


4 Allocation Type 
5-6 File Type 
0O Reserved 


O1 Sequential 
10 Relative Record 
11 Key Indexed 

7 Write Protection Flag 
O Not Write Protected 
1 Write Protected 

8 Delete Protection Flag 
O Not Delete Protected 
1] Delete Protected 

9 Temporary File Flag 
O Permonent File 
1 Temporary File 


10 Blocked File Flag 
O Blocked 
‘1 Unblocked 
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Table 5-3. Information Returned for Read File Characteristics Operation 
(Continued) 


5.4.2.7 Forward Space (0614) 


Byte 
Bits 


11 
12 


13-15 


10 
11 


10-11 
124+4(N-1) 


0-4 
5 


1344(N-1) 
1444(N-1) to 
1544(N-1 


Contents 


Reserved 

Immediate Write Flag 

O Write Buffers When Necessary 

1 Write Buffers Every Change 

Reserved 

Physical Record Length 

Logical Record Length 

End-of-Media for the File (Number of logical re- 
cords for sequential and relative record files, 
number of blocks for key indexed files) 

For Program Files Only: 

Sectors/Blocks 

Sectors/ADU for Disk Type 

For Key Indexed Files Only: 

Number of Keys defined for the File 


Keyflags 

Reserved 

Key Required Flag (Subordinate Keys Only) 
QO Key Required 

1 Key Not Required 


Reserved 

Duplicates Flag 

O Duplicate Key Values Not Allowed 
1 Duplicate Key Values Allowed 
Key Length 

Key Offset 


Where N ranges from 1 to 14 and is the number of keys defined for the 


file. 


The Forward Space operation applies to sequential and relative record 
files, The number of logical records to be spaced over is placed in by- 
tes 10 and 11 of the call block, and the forward space operation spaces 
forward the specified number of logical records or until an end-of-file 
(EOF) record is encountered, If an EOF record is not encountered, zero 
is returned in bytes 10 and 11 of the call block. If an EOF record is 
encountered the tape is positioned following the EOF record, the EOF 
flag (byte 4, bit 2 of the call block) is set, and the number of records 
remaining to be spaced is returned in bytes 10 and 11 of the call block. 


5.4.2.8 


5.4.2.9 
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Backward pace 07 


The Backward Space operation applies to sequential and relative record 
files. The number of logical records to be spaced over is placed in by- 
tes 10 and 11 of the call block, and the Backward Space operation moves 
in the reverse direction the specified number of logical records, or un- 
til an end-of-file (EOF) record is encountered, If an EOF record is not 
encountered, zero is returned in bytes 10 and 11 of the call block. If 
on EOF record is encountered, the file is positioned so that the next 
read operation encounters the EOF record, the EOF flog (byte 4, bit 2 
of the call block) is set, and the number of records remaining to be 
spaced is returned in bytes 10 and 11 of the call block. 


Read ASCII (09:4) 


. The Read ASCII operation reads a record of the specified file and stores 


the data, packed two characters per word, in the buffer at the address 

in SVC bytes 6 and 7, The maximum number of characters in the buffer is 
placed in bytes 8 and 9. The actual number of characters stored is placed 
in bytes 10 ond 11, This number specifies the number of characters in the 
record or the value in bytes 8 and 9, whichever is less. For a sequential 
file, if an end-of-file occurs, file management sets the EOF bit and sets 
the character count in bytes 10 and 11 to zero. If an odd length record 
is read, on extra character is placed in the buffer but the actual (odd) 
number of characters in the record is still placed in bytes 10-11. When 
the file is a relative record file and the read operation is successful, 
file management increments the record number in bytes 12 through 15, 


5.4.2.10 Read Direct (OA), ) 


5.4.2.1] 


5.4.2.12 


The Read Direct operation is identical to the Read ASCII operation. 


Write ASCII (0Bi.,) 


The Write ASCII operation transfers the dato in the buffer at the ad- 
dress in bytes 6 and 7 to the specified file. The choracters in the buf- 
fer are packed two per word, Bytes 10 and 11 contain the number of cho- 
racters to be written, When the file is o relative record file and the 
write operation is successful, file management increments the record 
number in bytes 12 through 15, A Write ASCII operation to a sequential 
file clears any end-of-file indication for the current record or for a 
subsequent record. 


Write Direct (0C 4) 


The Write Direct operation is identical to the Write ASCII operation. 


5.4.2,13 Write EOF (0D, ) 
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The Write EOF operation generates an end of file indicator in the file. 
Any number of EOFs may be written to o sequential file which allows di- 
viding a file into subfiles, Only one EOF is maintained for o relative 
record file, however. 


5.4.2.14 


5.4.2.15 


5.4.2.16 


5.4.2, 17 


5.4.2.18 


5.4.2.19 
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Rewind (OE 1, ) 


The Rewind operation simulates the rewinding of a magnetic tape file, 
causing the next operation performed on the file to access the first 
record in the file (not a subfile), when the specified file is a sequen- 
tiol file, When the file is a relative record file, file management 
places a zero in the record number field. When the file is an indexed 
file, the operation is ignored. 


Unload (OF), ) 


The Unload operation is ignored for all types of files. 


Rewrite (10 


The Rewrite operation backspaces a sequential or relative record file 


one record, and writes o record to replace the record previously read, 

The write portion of the operation is similar to the Write ASCII func- 

tion, If the character count indicates that the updated record is not @ 
the some length as the record on file, the operation is terminated, on. 

error code is returned, ond the record is not rewritten. Rewrites on 

blank-suppressed files are allowed providing the length of the record 

remoins the some, 


The Rewrite operation does not alter an end-of-file, and when a Rewrite 
operation is attempted on the end-of-file record the rewritten record is 
lost. 


Modify Access Privileges (1] 


This operation modifies the current access privileges to a new value. 
When the new access privileges cannot be granted, the old access privi- 
leges are retained. 


Length of SVC block: 12 bytes. 
Specifies the new privileges: bits 3, 4 of byte 5. 


en Extend (12 


The Open Extend operation opens a file and positions the file at the @ 
last EOF in the file. If the file ends with multiple EOFs the file is 
positioned to the first EOF of the ending group of EOFs. 


Unlock (4A 


The Unlock operation allows the user to release exclusive control of any 
previously locked record, The record to be unlogked may have been locked 
by any other task os well as the unlocking task.’ The record to be un- 
locked is specified in bytes 12-15 for relative record files ond is the 
current record for sequential files. 
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5.4.3 Multi-Key Indexed Files 


A multi-key indexed file is a disk resident structure used to store and 
retrieve data in a manner unique to this type of file. Each entry of 
data made to the file is'called a record. The characteristic that sepo- 
rates key indexed files (KIF) from other file types is that the records 
of other files ore read by identifying their position in the file, while 
the records of key indexed files ore read by identifying a portion of 
the content of the record, Thus, a user need not search the file for the 
desired record, only identify it by content. 


5.4.3.1 Key Indexed File Keys 


5.4.3.2 
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A portion of a record used to identify the record is called a key. A key 
is defined at the file level, therefore applying to every record in the 
file. It is a static set of values that cannot be changed except by re- 
constructing the file. A key indexed file must have at least one key; 
otherwise there would be no way of identifying the records. The maximum 
number of keys possible is 14; thus, the term "multi-key indexed file", 


The first key defined is the primary key and the others ore defined as 
secondary keys. The primary key need not identify the first portion of a 
record, and there may be secondary key fields physically before the pri- 
mary key within o record. 


Key indexed file keys are defined at file creation time (see the CFKEY 
SCI command), and may be from one to 100 characters long. A key has two 
characteristics associated with it: it may or may not permit duplicates, 
and it may or may not be modifiable, 


If the value of a key must be unique throughout the entire file, the key 
should be defined as not permitting duplicates, This will restrict any 
record from being inserted into the file if a record already exists in 
the file with a key volue equol to the new value of the record. For ex- 
omple, keys such as employee numbers and social security numbers should 
be non-duplicatable, while keys such as names ond salaries should per- 
mit duplicates, 


The other characteristic shared by all keys is modifiability, A key 
should be modifiable if its value may change after it has been inserted 
into the file. A key containing a person's salary should be modifiable, 
while a key containing the person's social security number should not 
be modifiable, If the value of a non-modifiable key contains incorrect 
data when it is entered into the file, the only way to correct it is to 
delete the record and then reenter it. The primory key is alwoys non- 
modifiable, . 


Key Indexed File Records 

As records are entered into a key indexed file, they are logically sorted 
by each key. It is as if there is a separate copy of the record for each 
key of a record, agd these copies are sorted by each key’s value using a 
given character code, such os ASCII. If more than one record has the some 
key value, they will be sorted in the order they were entered (the first 
one entered will be before the second one entered). 
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The records of a key indexed file may be read either randomly or sequen- 
tially. When the records are read randomly, a key number ond key value 
must be given for each read operation. When the file is read sequentially, 
a key number and key value need only be given the first time. From then 
on the records may be read in sorted sequentiol order either forward or 
backwards, The records are sorted with respect to the key used in the 
initial read. 


5.4.3.3 Key Indexed File Key and Record Example 


Since a key is defined for all records in the key indexed file, the re- 
cords should contain similar information, at least for the key portion, 
Similar information, for example, could be a number (social security or 
employee number) or a nome, A key indexed file record, and the keys the 
record may be broken into, are illustrated in the following example. 


@ 1-9 10-20 21-30 31-40 414600 AT 48-52 
VRUDDENE DOE JOHN ANDREW Ww M O11 
Key Columns Definition 
| 4) - 4 Employee Number 
2 0! - 09 Social Security Number 
3 10 - 20 Last Name 
4 21 - 30 First Name 
5 31-40 Middle Name 
6 10 - 40 Full Name 
7 47 - 47 Sex 
8 48 - $2 Monthly Salary 


The record is 52 characters long ond contains seven fields, but because 
the nome fields are used in more than one key, there are eight keys. In 
the example, the end of one key touches the beginning of the next. This 

@ is not a requirement, If, for data entry purposes, it is easier and/or 
clearer to leave one or more blanks between the keys, it may be done, 
Also, in the example, every column of the record is defined to be in at 
least one key. This, also, is not required, Quite often only a small por- 
tion of the record is defined to be part of a key, while the rest of the 
record contains data, The only requirements ore that there be a primary 
key, and that no key is longer than 100 characters. 


Since the primary key need not be in any particular position in a re- 
cord or have any qualities different from other keys, there is no way 
to determine which key is the primary key by looking at ao key indexed 
file record, However, the primary key can be determined by doing oa Map 
Key Indexed File (MKF) SCI command. The primary key will be identified 
as key number one. ~ - 
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5.4.3.4 


5.4.3.5 
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Key Indexed File Algorithms 


There are two different algorithms to place and retrieve records for a 
key indexed file; a hashed placement scheme and a sequential placement 
scheme, Only one algorithm can be included with a system at SYSGEN time, 


Under the hashed placement scheme, the primary key is hashed to indicate 
where the record is kept in the file, This method is used by TAXO release 
V100 systems. For more information on this method, see Appendix E. 


NOTE 

Beginning with TAXO release V200 systems, the hashed placement 
scheme should be used if: it is not desired to convert hashed 
key indexed files (generated for release V100 systems) to se- 
quential placement key indexed files; or, key indexed files 
created on a TAXO V200 system are to be run on a pre V200 re- 
lease system, which only supports the hashed placement scheme. 


The sequential placement scheme, which is supported only on TAXO release 
V200 systems, is recommended instead of the hashed plocement scheme, This 
method is in most cases faster and requires less disk space for a file, 
However, the hashing scheme is faster in the case of a Read by Primary 
Key operation, because under the hashed placement scheme, the primary 
key is hashed to indicate where the record is kept in the file, and the 
file structure is not searched, Therefore, a Read by Primary Key opero- 
tion is faster than a Read by Key operation. Under the sequential place- 
ment scheme, there is no special handling of the primary key, so ao Read. 
by Primary Key operation accesses the record at the same speed as the 
Read by Key operation, 


Key Indexed File Supervisor Call ond Currency Blocks 


The supervisor call block for key indexed files (figure 5-2), is common 
to the coll block used by other file types (figure 5-1). The only items 
thet make the call block for key indexed files different from the call 
block for sequential files, is thet bit 2 of the user flags field is de- 
fined to indicate a key is provided, and bytes 12-13 contain a pointer 
to a block of information known as the currency block, 


Currency is the name given to the block of information that describes a 
logical position within a key indexed file, This information includes an 
informative code, a key number, a pointer to onother block, and 16 bytes 
defined and used by the operating system, The pointer is to a set of cha- 
racters equal in length to the length of the key whose number is indicated 
in the currency block. The set of choracters may or may not be an actual 
value of a key in the file, but in this manual it is called a key value. 


In generol, the currency is set so that the record read by a Read Next 
operation will be the one following whatever record is affected by the 
previous operation performed. For exomple, if the some currency blocks 
ore used, a Read Next operation after an Insert operation will get the 
record following the inserted record; after o Delete operation, it will 
get the record following the deleted record; and after a Read operation, 
it will get the record following the one just read. 


5/20 


KIF CALL BLOCK OPEN 


| co | status cove fof fefsted stot? 
10 OPCODE } twNo | \\ DO NOT REPLACE 
ACCESS 
SYSTEM FLAGS USER FLAGS INITIATE PRIVILEGES 
(70 
DATA GUFFER ADDRESS 
LOGICAL. RECORD LENGTH 
CHARACTER COUNT 
CURRENCY GLOCK ADDRESS 


o2 


o4 


OTHER KIF CALLS 


LOCK AUNLOCK 


a6 


06 


KEY SPECIFIED 
INITIATE 170 


CURRENCY BLOCK 


sige 
KEY AOORESS 


KEY 


USER OEFINED 
KEY 


KIF Call Block, Currency Block, and KEY Relationship 


REQUIRED 

FOR FILE 
MANAGEMENT 

(MUST BE AVAILABLE) 


Figure 5-2. 


@ 
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5.4.3.6 Key Indexed File Opcodes 


5.4.3.6.1 
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Key indexed files support o set of I/0 opcodes unique to this file type 
‘as well as some of the opcodes used by other file types. The common op- 
codes shared by key indexed files and other file types are Open, Open 


_ Rewind, Close, Forward Space, Backspace, Rewind, and Read ASCII, 


NOTE 
Except for the Close operation, the common spcodie work only 
with sequential placement key indexed files. 


In the following paragraphs, the common opcodes are discussed first, 
followed by a discussion of the opcodes unique to key indexed files, In 
the paragraphs discussing unique opcodes, a C preceding the byte number 
means the byte is in the currency block, 


en (>00 


A key indexed file opened with this opcode cannot have any of the unique 
key indexed file operations performed to it. The only operations per- 
mitted are Close, Forward Space, Bockspace, Rewind, and Read ASCII. The 
records are accessed in sorted order by the primary key. For instance, 
when a file is opened, a few records ore read or skipped over, and then 
the file is closed and reopened; the logical position in the file is the 
same as it would have been if the file had not been closed and reopened. 
That is, the Open operation does not automatically position to the lo- 


gical beginning of a file, unless it is the first Open operation for the 


specified LUNO, 
The fields of the call block used by the Open operation are: 


Input: 
Byte Bit Contents 
2 Opcode, Must be >00. 
3 LUNO assigned to the key indexed file. 
5 3-4 Access privileges, | 
Code Meaning When Set 
00 Exclusive WRITE 
ol Exclusive ALL 
10 Shared 
1 Read Only 
Output: 
Byte Bit Contents 
1 Error Code Returned. 
6 File type code. Should be 3. 
7 File indicator. Must be >FF, 
8,9 Defined logical record length if this field 


was initially zero. 
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5.4.3.6.2 Open Rewind (>03) 


A key indexed file opened with this opcode cannot have any of the unique 

operations performed to it. The only operations permitted ore Close, For- 
ward Space, Backspace, Rewind, and 'Read ASCII. The operation sets the re- 
cord number to the first logical record in the file; the record with the 

"smallest" primary key. As in the Open operation, records are sorted off 

the primary key. 


The fields of the call block used by the Open Rewind operation are: 


Input: 
Byte Bit Contents 
2 Opcode. Must be >03 
3 LUNO that is assigned to the key indexed file. 
5 3-4 Access Privileges. 
Code Meaning When Set 
00 Exclusive WRITE 
01 Exclusive ALL 
10 Shared 
11 Read Only 
Output: 
Byte Bit Contents 
1 Error code returned, 
6 File type code, Should be 3, 
7 File indicator, Must be >FF. 
8-9 Defined logical record length if the field 


was initially zero, 


5.4.3.6.3 Close (>01) 


® 


This operation can be used with both the common Open operations, and the 
Open Random operation which is a unique opcode of key indexed files 
(which will be discussed later). The Close operation should be used to 
ensure data integrity, The fields of the call block used by the Close 
operation are: 


Input: 
Byte Bit Contents 
2 Opcode. Must be >01. 
3 LUNO assigned to the key indexed file, 
Output: 
Byte Bit Contents 


1 Error code returned, 
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5.4,3.6.4 Forward Space (>06) = 


This operation skips forward over a number of logical records from the 
present record, If the number of records to be skipped exceeds the num- 
ber of records remaining in the file, the End-Of-File flag is set in the 
call block (bit 2 of byte 4), and the file is logically positioned be- 
fore the end-of-file. 


The records are sorted by the primery key. 


The fields of the call block used by the Forward Space operation are: 


Input: 

Byte Bit Contents 

2 Opcode. Must be >06, 

3 LUNO assigned to the key indexed file. 

10-11 Contains the number of logical records to skip 

over, 

Outputs 

Byte Bit Contents 

1 Error code. 

4 2 Set to one if the end of file was encountered, 

10-11 The number of records remaining to be skipped 


if bit 2 of byte 4 is set to |, otherwise 
these bytes contain a zero. 


5.4.3.6.5 Backspace (>07) 
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This operation skips backwards over a specified number of logical re- 
cords from the present record, The records are sorted off the primary 
key. If the beginning of the file is encountered, no error is returned 
and bytes 10-11 will contain the number of records remaining to be 
skipped. A non-zero value in bytes 10-11 is the only indication that the 
beginning of file was encountered. 


The fields of the call block used by the Backspace operation ore: 


Input: 

Byte Bit Contents 

2 Opcode. Must be >07. 

3 LUNO assigned to the key indexed file. 

10-11 Number of logical records to skip. 
Output: 

Byte Bit Contents 

1 Error code returned. 
10-11 Number of records remaining to be skipped 


if the beginning of file was encountered, 
Otherwise, zero. 


5.4.3.6.6 


5.4.3.6.7 
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Rewind (>0E) 


This operation resets the present record number to the first logical re- 
cord; which will be the record with the "smallest" primery key. 


The fields of the call block used by the Rewind operation are: 


Input: 
Byte Bit Contents 
2 : Opcode, Must be >0E 
3 ; LUNO assigned to the key indexed file. 
Output: 
Byte Bit Contents 
1 Error code returned, 


Read ASCII (>09) 


This operation transfers the present logical record that the file is 
positioned to into o buffer and positions the file to the next logical 
record, The next logical record is the record with a primary key equal 
to, or next lorger than, the primary key of the record transferred in- 
to the buffer. If the file is positioned to the logical end-of-file and 
a Read operation is executed, the end-of-file bit (byte 4, bit 2) in the 
call block will be set to one. 


Input: 
Byte Bit §—- Contents 
2 Opcode. Must be >09, 
3 LUNO assigned to the key indexed file. 
6-7 Address of the buffer into which the record 
will be transferred. 
8-9 The maximum number of characters to be trans- 
ferred into the buffer. 
Output: 
Byte Bit Contents 
1 Error code returned, 
4 2 Set to one if the end-of-file is encountered. 
10-11 The actual number of characters transferred 


into the buffer. 


5.4.3.6.8 Open Random (>40) 


Before any of the unique opcodes can be used, the file must be opened 
using the Open Random opcode. 


The fields of the call block used by the Open Random operation: 
Input: 


Byte Bit Contents 


2 Opcode. Must be >40, 
3 LUNO assigned to the key indexed file. 


5.4.3.6.9 
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Output: 
Byte Bit Contents 
1 , Error code returned. 
6 . File type code, Must be 3, 
7 File indicator, Must be >FF. 
8-9 Defined logical record length if this field 


was initielly zero, 


Read by Key (>42 1 


The >42 opcode is used to specify either the Read by Key or Read Current 
operation. The operation to be performed is designated by setting bit 1 
of byte 5 in the call block, When thot bit is 1, the Read by Key’ opero- 
tion is performed. When that bit is 0, the Read Current operation is 
performed (see paragraph 5.4.3.6. 10) 


The Read by Key operation reads the first record thot was inserted into 
the file with the specified key value, The Read Current operation reads 
the record identified by the currency information, instead of the record 
identified by the key number and key value. 


The record can be locked when it is read by setting bit 5 of byte 5 of 
the call block to one; setting this bit to zero indicates that locking 
is not desired. 


The fields of the call block used by the Read by Key operation are: 


Input: 
Byte Bit Contents — 
2 Opcode. Must be >42, 
3 LUNO assigned to the key indexed file 
5 1 Key specified, Must be 1. 
6-7 Address of the buffer to receive the record. 
8-9 Maximum number of records to be read. 
12-13 Currency block address, 
cC.1 Number of key being used. 
C 2-3 Address of the block that contains the wale 
of the key to be read, 
Key The value of the key to be used in finding 
the desired record. 
Output: 
Byte Bit Contents 
1 Error code returned, 


9-10 | Number of characters read, 


5.4.3.6, 10 
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Read Current (>42) 


The >42 opcode is used to specify either the Read Current or Read by Key 
operation. The operation to be perfprmed is designated by setting bit 1 
of byte 5, When that bit is 0, the Read Current operation is performed. 
When that bit is 1, the Read by Key operation is performed (see poragraph 
5.4.3.6.9), This operation reads the record identified by the currency 
information, The record can be locked when it is read by setting bit 5 
of byte 5 of the call block to one; setting this bit to zero indicates 
that locking is not desired. . 


The fields of the call block used by the Read Current operation are: 


Input: 
Byte Bit Contents 
2 Opcode, Must be >42, 
3 LUNO assigned to the key indexed file. 
5 1 Key specified. Must be 0, 
6-7 Address of buffer to receive the record. 
8-9 Maximum number of characters to be read. 
12-13 Currency block address. 
Cc Currency information set up by a previous 
command, 
Output: 
Byte Bit Contents 
1 Error code returned. 
9-10 Number of characters read, 
co Informative Code. 


5.4.3.6,11 Reod Greater (>41) 


This operation reads the record with the next larger key value than the 
specified key, If there is more than one record, the record that was in- 
serted into the file first will be read. The record can be locked when 
it is read by setting bit 5 of byte 5 of the call block to one; setting 
this bit to zero indicates that locking is not desired. 


5.4.3.6.12 Read Greater or Equal (>44) 


This operation reads the record with the next larger key value than the 
specified key; or, if one exists, reads the record with a key value equal 
to the specified key. If there is more than one record, the record that 
was inserted into the file first will be read. The record can be locked 
when it is read by setting bit 5 of byte 5 of the call block to one; 
setting this bit to zero indicates that locking is not desired. 


5.4.3.6.13 
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The fields of the call block used by the Read Greater or Equal operation 
are: - 


Input: 
bi 
Byte Bit Contents 
20 Opcode. Must be >44, 
3 LUNO assigned to the key indexed file. 
5 = Key specified. Must be 1. 
6-7 Address of the buffer to receive the record, 
8-9 Moximum number of characters to be read, 
12-13 Currency block address, - 
co Length of the specified key value, 
C1 Number of the key being used, 
C 2-3 Address of the block that contains the value 
of the key to be used. . 
Key The value of the key to be used in finding 
~ the desired record. 
Output: 
Byte Bit Contents 
1 Error code returned, 
9-10 Number of choracters read. 
co Informative code. 


Read Next (>45) and Read Previous (>48) 


These operations read either the next sequential record in the file from 
the present record, or the previous record in the file from the present 
record; the currency information is used to determine the correct record. 
If the currency information was set up using one of the Set Currency com- 
mands, the record presently pointed to by the currency information is 
read, instead of the next sequenticl or previous record. The record can 
be locked when it is read by setting bit 5 of byte 4 of the call block 
to one; setting this bit to zero indicates that locking is not desired. 


The fields of the call block used by the Read Next and Read Previous 
operations are: 


ae 


Input: 
Byte Bit Contents 
2 Opcode. Must be >45 or >48, . 
3 _2 =~ SLUNO assigned to the key indexed file. 
7-8 * S..49Maximum number of choracters to read, 
12-13 Currency block address. 
CA ~« Currency set up by a previous command. 
Output: a 
Byte Bit’ ~ Contents 
1 Error code returned, 
9-10 Number of characters read. 
co Informative code, 
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5.4.3.6.14 Set Currency Equal (>50), Greater (>52), and Greater or Equal (>51 


The Set Currency Equal (>50) operation sets the currency indicators to 
the record containing a key value equal to the one specified. 


The Set Currency Greater (>52) operation sets the currency indicators 
to the record containing the next larger key value than the one speci- 
fied, 


The Set Currency Greater or Equal (>51) operation sets the currency in- 
dicators to the record containing a key value equal to the one specified, 
if one exists. Otherwise, the currency indicators are set to the record 
containing the next larger key value than the one specified. 


The fields of the call block used by the Set Currency Equol,Greater, 
and Greater or Equal operations are: 


Input: 
@ Byte Bit Contents 
2 Opcode. Must be >50, >51, or >52. 
3 LUNO assigned to the key indexed file. 
12-13 Currency block address. 
co Length of the specified key value. 
Cc 1 Number of the key being used. 
2-3 Address of the block that contains the value 
of the key to be read, 
Key The value of the key to be used in finding 
the desired record. 
Output: 
Byte Bit Contents 
1 Error code returned, 
CoO Informative code. 


5.4.3.6.15 Delete by Key (>49) 


The >49 opcode is used to specify either the Delete by Key or Delete 
Current operation, The operation to be performed is designated by set- 
ting bit 1 of byte 5. When that bit is 1, the Delete by Key operotion 

is performed, When that bit is 0, the Delete Current operation is per- 
formed (see paragraph 5.4,.3.6.16). The Delete by Key operation deletes ~ 
the record with a key value equal to the one specified. If there is more 
than one record with an equal key value, the informative code >B4 is re- 
turned and the record is not deleted. A Delete Current command must be 
used if more than one record has a key value equal to the one specified. 


5.4.3.6. 16 


5.4.3.6. 17 
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The fields of the call block used by the Delete by Key operotion are: 


Input: 
Byte Bit 1 Contents 
2 Opcode. Must be >49, 
3 LUNO assigned to the key indexed file. 
5 2 ul Key specified. Must be 1. 
12-13 Currency block address. 
om Number of the key being used. 
C 2-3 Address of the block that contains the 
value of the key to be read, 
Key The value of the key to be used in finding 
the desired record, 
Output: 
Byte Bit Contents 
1 Error code returned, 
co Informative code, 


Delete Current _(>49) 


The >49 opcode is used to specify either the Delete Current or Delete 

by Key operation. The operation to be performed is designated by setting 
bit 1 of byte 5 in the call block. When that bit is 0, the Delete Current 
operation is performed, When thot bit is 1, the Delete by Key operation 
is performed (see paragraph 5.4.3.6.15). The Delete Current operation 
deletes the record pointed to by the currency indicators, : 


The fields of the call block used by the Delete Current operation ore: 


Input: 
Byte Bit Contents 
2 Opcode. Must be >49, 
3 LUNO ogsigned to the key indexed file. 
5 1 Key specified, Must be 0, 
12-13 Currency block address. 
Output: ~ 
Byte Bit Contents 
| Error code returned. 
co Informative code. 
Insert (>46 


This operation places a dato record into the key indexed file. The record 
must have a primary key value. Any secondary keys may be null if they 
are defined to be modifiable, A key is considered to be null if the first 
byte contains >FF or if it is entirely blank. A >B4 informative code is 
returned if a duplicate of a key is found and the key is defined as not 
having duplicates. 
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The fields of the call block used by the Insert operation are: 


Input: 
Byte Bit 


co 


5.4.3.6,18 Rewrite (>47) 


Contents: 


Opcode. Must be >46, 

LUNO assigned to the key indexed file. 
Number of characters in record. 
Currency block address. 

Number of the key to use in setting up 
the currency indicators. 


Contents 
Error code returned, 


Informative code, 


This operation replaces an already existing record with another one that 
may be smaller or larger than the original. Only keys defined to be mo- 
difiable may be changed with the Rewrite opcode, and the record must 
have been read with lock. The currency block set up by the Read, must be 
used by the Rewrite operation, 


The fields of the call block used by the Rewrite operation are: 


Input: 
Byte Bit 
2 


Byte Bit 


co 


5.4.3.6.19 Unlock Current (>4A) 


Contents 


Opcode, Must be >47, 

LUNO assigned to the key indexed file. 

If set to 1: Rewrite the record and keep it 
locked, 

If set to 0: Rewrite the record and unlock it 
ofterwards, — 

Number of choracters in record. 

Currency block address. 


Contents 
Error code returned. 


Informative code. 


This operation unlocks the record pointed to by the currency indicators. 


The fields of the coll block used by the Unlock Current operation are: 


Input: 
Byte Bit 


Contents 


Opcode, Must be >4A 

LUNO assigned to the key indexed file. 
Currency block oddress. 
Currency indicators set up by a previous command. — 
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5.4.3.8 
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Output: 
Byte Bit Contents 
1 , Error code returned. 
co Informative code. 


Portial Keys . 


All three of the set currency operations, and the Read Greater and Read 
Greater or Equal operations have a feature that permits specification 
of key values with fewer characters than the keys are defined to have. 
These are known os partial keys. 


If a partial key is used in one of these operations, the number of cho- 
rocters in the partial key is placed in byte O of the currency block and 
the partial key charocters are placed in the key block. The characters 
of a partial key will be compared against the beginning characters of the 
specified key. They can not be used to find a portion of the middle or 
end of a key. 


An example of partial key usage is if a key is defined to be a person's 
last nome, such as JOHNSON, a partial key could be used within a program 
to find all last names that begin with J, JO, JOH and so on. 


Error and Informotive Code 


Values returned in the status code field, byte 1 of the call block, are 
serious error codes ond, if they occur, the application program should 
probably be terminated, The error codes are discussed in ERROR MANUAL, 


The values returned in the informative code field, byte 0 of the currency 
block, may or may not be serious errors. They are intended to be an aid 
to the user and may occur in any properly functioning application program. 


The informative codes which may be returned to byte 0 of the currency 
block are: 


Value _ Meaning 

B3 There ore no more records to be read. 

B4 There are records with the same key value as that used 
to read the present record. 

B5 No record exists with the key or currency values 
specified, 

B7 The record to be locked is already locked. 

B8 No record exists thot satisfies the conditions set by 


the opcode and currency block. 


BD The next record cannot be found for a Read Next or Read 
Previous operation. Either currency has been destroyed 
or the record fas been deleted. 


Table 5-4 identifies the possible error and informative codes for the dif- 
ferent key indexed file unique opcodes, A."*" in front of the list of 
error or informative codes identifies the codes possible if the operation 
is performed with the record lock bit on (byte 5, bit 5 of the call block). 


Table 5-4 ° 

Opcode Command 

40 Open Random 

41 Read Greater 

42 Read by Key 

42 Reod Current 

44 Read Greater 
or Equal 

45 Read Next 

46 Insert 

47 Rewrite 

48 Read Previous 

49 Delete by Key 

49 Delete Current 

4A Unlock 

50 Set Currency 
Equal 

51 Set Currency 
Equal or 
Grester 

52 Set Currency 


Grecter 
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Error Codes 


05, 0D, BF, D7 
05, 0D, BF, 07 
05, 0D, B6, D7 
05, OD, BF, D7 
05, OD, BF, D7 
05, 0D, B1, B2 


CO, D7, £0 


05, 0D, BO, B2, B6 
89, BA, BE, CO, EO 


*05, 0D, BO, B1, B2, 
*B6, B9, BA, BE, CO, 


*D7,E0 
05, /D, B6, 07 


05, 0D, BO 
05, 0D, BO 
0D, B6, BA 
05, 0D, D7 


05, 00, D7 


05, 0D, 07 


Error ond Informative Codes for Key Indexed File Opcode 


Informative Codes 


B4, BS 
*“B4,B8, B7 


B4,B5 
“B4, 88, B7 


B4,B5 
*B5, B7 


B3,BD 
*B3, B7, BD 


B4,B5,B7 
B4,B7 
B5, B7 
B4,B8 


B4,B8 


B4,B8 
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5.4.3.9 Key Indexed File Usage 


When key indexed files are created using the sequential placement scheme, 
the maximum size of the file can be calculated fairly accurately. The 
accuracy of the final value, of course, depends on the accuracy of the 
values supplied by the user creating the file. Also of significance is 
the way the file allocates disk spoce. If the file is created with an 
initial allocation larger than the required amount, the calculated maxi- 
mum size will probably be less than the actual size. This depends on 
accuracy of the input parameters, By creating the file with a smaller 
than actual maximum number of logical records, and permitting it to dy- 
namically allocate more space, the calculated maximum size should always 
be a bit larger than the actual size. 


The parameters required for calculating disk usage for a key index file 
are: 

e The physical record size 

e The average blank suppressed logical record size 

e The sizes of all the keys 

e The ADU size of the disk on which the file will be created 

e The maximum number of logical records 

e Whether the input will be sorted 


The most difficult parameter to estimate is the average blank suppressed 
logical record size. This is the average size of a logical record if all 
blanks were taken out of all the records, The accuracy of this parameter 
is critical to the total quality of the result, The maximum number of 
logical records can be easily determined if the records cre already in a 
sequential file. Otherwise, this value must also be estimated. The other 
values are well defined and should require no estimations. 


The disk allocation of a key indexed file can be broken down into three 
definite areas, The first is the prelogging area. It is the only area 
ovt of the three that has an absolute value. The number of physical 
records of disk space required for this area may be calculated using the 
following formula: 


(18 * K) + 3 = NPRprelog 
where: 


K = number of keys 


NOTE 
In the following equations, | | means to round the enclosed calcu- 
lation down to the nearest integer and means to round the num 


ber up to the nearest integer. 


The second area is used for the B-tree nodes. These ore the records that 
contain the structures that make key indexed files function differently 
from other file types. The approximate number of physical records re- 
quired for these structures is defined with the following equotions: 


Fee = X 
KS + 6 


fap]. foam itt] em 


Physical record size 

Maximum number of logical records 

Size of the key 

0.1 if the input is already sorted with respect 
to the key, otherwise, it equals 0.25 


Az 
n 
fouw a 


A calculation must be performed for each key to be in the file. Thus, if 
there ore to be three keys in the file, there must be three B-tree values 
in the finol physical record summation, 


The last area is used for the actual data records. The approximate num- 
ber of physical records required for this area is defined by the follow 
ing equation: 


= -16 =X 
LRS + 6 


[AS] nerdete 


= Physical record size 
#LR = Maximum number of logical records 

= Average blonk suppressed logical record size 
(if there is only one key in the file, this 
value should not include the length of the 
key, i.e., assume the key consists of all 
blanks) 


The 16 bytes subtracted from the PRS is 14 bytes of overhead at the be- 
ginning of each record, and 2 bytes at the end of each record. 


The total number of aes records required is calculated by the fol- 
lowing equation: 
NPRprelog + NPRdata + 5 NPRb-tree i 
iz] 
where: 
= number of keys 

The total number of ADUs required is therefore defined through the fol- 
lowing equation: 


if PRS > ADU 
then (] *NPRtotal = Number of ADUs required 


1 . ad 
else ‘ADU *NPRtotal | = Number of ADUs required 
| ERs | che 
where: 


PRS = Physical record size 
ADU = ADU size 
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The following are examples of these calculations. 


Example 1: 


5 


PRS = 864 

ADU = 864 

LRS =60 (Average blank suppressed - key size) 
KS =20 

K =] 

#LR = 800 


Sorted input (SPLIT =.1) 
A) NPRprelog = (18° 1) + 3 = 21 


B) =| =22 


e fx] [fell 


NPRb-tree = 28 
C) (864 - 14 = 12 
60 +6 
NPRdata = [2 = 67 
12 


NPRtotal = NPRprelog + NPRb-tree + NPRdata 
= 21 + 28 + 67 
= 116 


ADUs = | 864 * 116 = 116 
864 


®. 

~ 
8g 
~ 
8 
Pe) 
a 
g 
- 


@ 
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Example 2: 
5 
PRS = B64 
ADU az 864 
LRS = 60 
KS} =20 
KS2 =20 
KS3 = 20 
K =3 
#LR = 2600 


A) 


B) 


Cc) 


Random input (SPLIT = .25) 


NPRprelog = (18 * 3) + 3 = 57 

$64 — = 32 

20 + 6 

2600] + 25 * 2600} | = 82 + 21 
32 32 


NPRb-tree(!1) = 103 key 1! 
NPRb-tree(2) = 103 key 2 
NPRb-tree(3) = 103 key 3 


864 - 14 = 12 
60 + 6 
NPRdata = [=] = 217 


NPRtotal = NPRprelog + NPRb-tree(1) + NPRb-tree(2) + NPRb-tree 
_(@) + NPRdata 
= §7 + 103 + 103 + 103 + 217 
= 583 


ADUs = fast] * $83 = 583 
864 
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5.5 File Utility Operations 


File utility operations permit general access to resources but do not 
necessarily transfer data, 


With file utility operations a task may create files, assign LUNOs to 
files, delete files, release LUNOs, plus other functions without operco- 
tor intervention. This allows a task to acquire its own resources and 
reduce the workload placed on an operator. The utility call block is 
shown in figure 5-3 and the individual bit and byte meanings are given 
in table 5-5. Key indexed files require a Key Indexed Call Expansion 
block as shown in figure 5-4 when the file is created. One of the entries 
in the utility block is a pointer to the key indexed call *expansion 
block. 


ene eee ERC nae 
oe 
a 
Teeter 


REQUIRED 


UTILITY FLAGS 


DEFINED LOGICAL RECORO LENGTH 
O€FINEO PHYSICAL RECORD LENGTH 


REQUIRES 


u7iee 
SaeATE 
orpcooges 


RESERVED FOR PASSCODE ADDRESS 


€ 
LOCK 
SECONDARY FILE 
ALLOCATION 


Figure 5-3. 1/0 Supervisor File Utility Call Block 
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Table 5-5. File Utility Call Block Bit Assignments 


Byte Bit Meaning 

0 All SVC code. This code is zero for all I/0 operations 

1 All Status Code (see Error Manual) 

2 All Utility Opcode. This byte is set by the user to specify 


the requested utility operation as follows: 


Opcode Operation 
90 Create File 


91 Assign LUNO to pathnome 
92 Delete File 
93 Release LUNO assignment 
94 Reserved 
95 Assign new file name (Rename) 
96 Unprotect file 
97 Write protect file 
98 Delete protect file 
99 Verify pathname 
9A Add alias 
9B Delete alias 
9C Define forced write mode 
3 LUNO, This byte specifies the LUNO to be used in the 


operation, It is supplied by the user except when the 
Generate LUNO bit is set on.an Assign operation. 


4-11 Not Used. Reserved for compatibility with other calls. 


12-13 : When creating a key indexed file, the information about 
the number of keys and key positions is defined by an 
expansion block. This block varies in length depending 
upon the number of keys in the file. The format of 
this block is shown in figure 5-4, For program files, 

_ byte 13 contains the maximum number of tasks. 


When creating a directory file, the value is used to 
establish the default physical record size that is to 
be used for subsequent file creations under this direc- 
tory. 


14, 15 -For progrom files, the moximum number of procedures is 
specified in byte 14; the maximum number of overlays 
is specified in byte 15. These bytes are not used for 
other types of files. 


16, 17 Utility Flags. These flags are used for assign LUNO and a 
create file operations. For all other new utility ope- 7 
rations, these flags should be set to zero. 


16 0 _ Created by Assign. This bit is set after an assign LUNO 
operation in the Auto Create option (bit 6) was speci- 
fied and assignment actually caused the file to be 
created. 
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Table 5-5, 
Byte Bit 
16 1, 2 
16 3, 4 
16 5 

16 6 

16 7 

17 ¢) 

17 1 

17 2 
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File Utility Call Block Bit Assignments (Continued) 


Meaning 


File Usage Flog. The user sets this field to indicate 
the special usage of this file. For create operations 
this indicates that the file will be used for a spe- 
cial purpose. 


Code Meaning 


00 No special usage 
01 Directory file 
10 Progrom file 

11 Image file. 


Scope of LUNO Assignment. These bits define the scope 
of a LUNO assignment or release. 


Code Meaning 


00 . The LUNO is task local 

01 - The LUNO is terminol local 
10 The LUNO is global 

11 Reserved 


Generate LUNO, If this flag is 1, TAXO automatically 
generates ao LUNO number ond returns it in the LUNO 
field (byte 3). If this field is a 0, the content of 
the LUNO field is used. This flag applies to the assign 
LUNO operation only. 


Automatic Create, User sets to one to request automatic 
file creation by the assign LUNO operation (91 ). If 
set, the call block must contain sufficient information 
to permit file creation. 


Reserved, Must be zero, 


LRL Flag. User sets this bit to a one for any create 
operation, including Auto Create, when the file is to 
be created with the logical record length in bytes 18 
and 19 of the utility block, If this flag is zero, 
bytes 8 and 9 are used. This flog is for compatibility 
only. Users should set this flag to a one, and use 
bytes 18-19 for logical record length. 


Temporary File, If this bit is one, the file specified 
will be ao temporory file. This applies to create and 
to assign LUNO operctions with the Auto Create option 
specified. This file is allocated on the system volume 
if the pathname address is zero. 


Immediate Write. Set to ) if all disk file writes are 
to be written immediately, i.e., before I/0 completion 
is returned to the user. This bit has meaning for the 
Create File and Define Force Write Mode operations. Se- 
lecting immediate write assures dato is transferred to 
disk on each write but is inefficient on blocked files. 
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Table 5-5, File Utility Call Block Bit Assignments (Continued) 


Byte Bit 
17 3, 4 
17 5 

17 6, 7 
18, 19 

20, 21 

22, 23 


Meaning 


Data Format. These bits specify the data format of the 
records, Valid codes are: 


Code Meaning 

00 Normal record image 

01 Blank suppressed 

10, 11 Reserved for new data formats. 


Multi-key indexed files are always blank suppressed. 


Allocation Flag. A 1 indicates the file may grow beyond 
the initial allocation requested at file creation. 


File Type. Set to one of the following codes to specify 
the file type when the file is created. This field is 
ignored except for create operations. The file type is 
returned on all open operations. 


Code Meaning 


00 Reserved 

01 Sequential File 

10 Relative record file 
11 Key indexed file 


Logical Record Length. This field is required for all 
files using fixed-length logical records. Its only use 
for files with variable length logical records is in 
calculation of file size when the file is created, In 
this case if the field is zero a default value depen- 
dent on file type is used, This opplies to create ope- 
rations only. The logical record size may no exceed ~ 
32K bytes. 


Physical Record Length, This field specifies the physi- 
cal record length to be used for file I/0. If this field 
is any value less than twice the logical record length, 
the file will be unblocked. In variable logical record 
length files this field specifies the size of the block- 
ing buffer and the physical record to be used. If this 
field is zero o defavlt is used. The defavlt value will 
vary depending on the disk type in use. This applies 

to create operations only. 


Pathname Pointer. These two bytes contain the address 
of a pothnome used for RENAME FILE, ADD ALIAS, DELETE 
ALIAS, PROTECTION OPERATIONS, ASSIGN LUNO, CREATE FILE, 
AND DELETE FILE operations. The pathname format is os 
follows: 


Byte O - Pathname length in bytes 
Bytes I-n - Pathname 


The pathname syntax is described in Volume II. 


Toble 5-5, 
Byte Bit 


32, 33, 
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File Utility Call Block Bit Assignments (Continued) 


Meaning 
Passcode Pointer. (To be implemented in a future release, ) 
Reserved for Passcode Pointer. 


Initial File Allocation. For a bounded file this speci- 
fies the total file size, and for an unbounded file it 
specifies the initial allocation (which may later be 
expanded). On an unbounded file this field can be o zero 
to specify a default initial allocation. This applies 
to create operations only. 


Secondary File Allocation. This field is treated exactly 
as the Initial File Allocation field except that it is 
used to specify the amount of space to be allocated 
when an unbounded file is expanded. If zero, a default 
is used. This applies to create operations only. 
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BYTE o 


ANTICIPATED MAXIMUM NO, OF LOGICAL 
RECORDS IN FILE (ESTIMATE ) 


FLAGS 


hee | OFFSET TO PRIMARY KEY 


NUMBER OF CHARS IN 
PRIMARY KEY 


2 Finst si ECONDARY KEY 2 ie . 
DEFINEO 
ie eo ee 
REPEAT FOR DEFINITION OF SECONDARY 
KEY FIELDS 2 THROUGH (N-2) 
ea pee BOSE EanBAn ue 
(N- 1) SECONDARY KEY 
Te eeeerern 
NOTE 
FLAG BYTE(S) 
Bits Meaning 
0-4 None. Set to 0. 
5 Set if this subordinate key may be modified, Reset if 
it must not be modified and must be present on insert. 
6 0 
7 Set if duplicates are allowed on this key. 


Figure 5-4, Key Indexed Definition Block 
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5.5.1 | Greate File (9014) 


This operation is used to create a file by a task. The call block is 36 
bytes long. The following fields of the block need to be specified, 


byte 16 (utility fleg) 


bits 1, 2: 00 if creating ordinary relative 
record, sequential, or key index 
file, 


01 if creating directory relative 
record file. 

10 if creating progrom relative 
record file. 

11 if creating image relative re- 
cord file, 


byte 17 (utility flag, 2nd half) 


bit 0: Logical Record Length flag. 
1 LRL specified in bytes (18-19). 
O LRL specified in bytes (8-9). 
bit 1: Temporary flag. 
1 if temporary file. 
O if permonent file. 
bit 2: Force immediate write. 


1 if all disk writes are to be imme- 


diate (this bit is always set for 
key index files). 
3 O if disk writes can be deferred. 

bits 3, 4: Data format. 

00 if normal record image. 

Ol if blank suppressed. 
bit 5: Expandable flag. 

1 if file expandable, 

O if file not expandoble, 
bit 6, 7: File Type. 

00 if device. 

O1 if sequential, 

10 if relotive record, 

11 if key indexed file, 


' bytes 18, 19 (logical record length) if zero assume default. 
bytes 20,21 (physical record length) if zero assume default, 


bytes 22, 23 (pathname address) This field specifies the pathname 


of the file to be created. For tem- 


porary files with system generated 
file names specify zero, 


bytes 28-31 (initial file allocation) Specify the initial size (i.e., num- 
ber of records) collocated to the file 


being created. Must be specified 
(GT 0) for nonexpandable. 


O = default (i.e., for expandable) 


ao 
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bytes 32-35(secondary file allocation) Used only with expandable files 


5.5.1.1 Create Sequential File Example 


to specify number of records for 
secondary allocations (strictly 
speaking, specifies Ist secondary 
allocation. Successive allocations 
will be larger.) 


O = default. 


A sample call block for creating a sequential file with: 


e 8&0 byte logical records 

e@ 288 byte physical records 

e 1000 record initial allocation 

e 500 record secondary allocation 
e blank suppression 

@ pathname of PACK,USER, TEXT. FILEO! 


DATA 0 

BYTE >90,0,0,0 
DATA 0, 0.0, 0,0 
BYTE 0, >8D 


CRSEQ 


DATA 40 


DATA 288 
DATA PATH 

DATA 0, 0 

DATA 0, 1000 

DATA 0, 500 

BYTE NAME-S-1 

TEXT ‘PACK. USER. TEXT. FILEO!' 
EQU S$ 


PATH 


NAME 


CREATE FILE 


LRL, BLANK SUPPRESSED, 
EXPANDABLE, 

FILE TYPE. 

RECORD LENGTH LESS AVERAGE 
NO. 

BLANKS 

PHYSICAL RECORD LENGTH 
PATHNAME ADDRESS 


INITIAL ALLOCATION 
SECONDARY ALLOCATION 
PATHNAME LENGTH 
PATHNAME 


Note that the logical record length has been specified as 40 on the as- 
sumption the average record contains 40 trailing blanks, 
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5.5.1.2 Create Key Indexed File Example 


The following program uses the Auto Create operation to create a key in- 
dexed file whose attributes are as follows: 


e 100-character nominal logical records (average number non-blonk cho- 
racters/record). 


@ 900-choracter physical records. 
@ 2 keys — both nonmodificble and no duplicates allowed. 
e 10,000 anticipated logical records, | 


TASK DATA WS. PC, 0 
ws BSS 32 
CRKEY DATA 0 
BYTE >91, 0.0.0 AUTO CREATE 
DATA 0.0.0 
DATA KEY, 0 ‘KEY BLOCK ADDRESS 
BYTE >06 GENERATE LUNO, AUTO CREATE 
BYTE >87 LRL, EXPANDABLE KIF 
DATA 100 LOGICAL RECORD LENGTH 
DATA 864 PHYSICAL RECORD LENGTH 
DATA PATH PATHNAME ADDRESS 
DATA U. 0 . 
DATA 0,0 INITIAL ALLOCATION 
DATA 0,0 SECONDARY ALLOCATION 
*KEY DEFINITION BLOCK 
KEY BYTE KEYS-S-1, 0 
DATA 0, 10000 10,000 MAXIMUM LOGICAL 
| ; RECORDS 
DATA 2 2 KEYS 
DATA 12 IST KEY 12 CHARACTERS 
DATA | IST KEY BEGINS ON 1ST CHAR 
DATA 6 2ND KEY 6 CHARACTERS 
DATA 6 2ND KEY BEGINS ON 6TH CHAR 
KEYS EQU $ 
BSS 22 
PATH BYTE PATHS-S-1 
TEXT ‘.JB. KEY’ 
PATHS EQU $ 
EOT BYTE 4 
EVEN 
PC XOP @CRKEY, 15 
XOP @EOT, 15 
END 


5.5.2 Assigning A_LUNO (91 


This operation is used to associate a LUNO with o file. Ordinarily, the 
file preexists, but the system may create one if it does not. (This is 
called autocreate,) Also, the LUNO may be explicitly given or the system 
may generate it, Thus, there are four combinations of options possible ~~ 
with this operation: 7 


1, Preexisting file and specified LUNO. 


2. Preexisting file and system generated LUNO, 
3. System generated file and specified LUNO. 


4. System generated file and system generated LUNO, 
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If the user sets the autocreate flag (byte 16, bit 6 = 1) ond the file 


does not already exist, then the system attempts to create the file using 


the fields indicated in the description of the create file (90) opcode. 
It will also assign a (possibly generated) LUNO to the newly created 
file (assuming thot the creation attempt succeeded). 


If the autocreate flag is not set the system just tries to assign the 
LUNO to the preexisting file. 


Once the file exists (either preexisted or created in earlier steps of 
operation) the actual LUNO assignment is the some. These fields are re- 
levant to the actual assignment of LUNOs. 


byte 3 - (LUNO) - explicitly stated LUNO number 

byte 16 - (utility flogs) 

bits 1, 2: file usage OO no special usage 
O1 directory file 
10 progrom file 
11 image file 

bits 3, 4: scope of LUNO 00 task local 


01 terminal local 
10 global 


bit 5: generate LUNO 1 system generates LUNO 
O use byte 3 
bit 6: autocreate 1 system creates file if it 
doesn't already exist 
O file must already exist 


bytes 22, 23: Pathnome address 
The correct file usage flags must be set in order to assign a LUNO to a 
directory, progrom, or image file or on error is returned. However, set- 


ting these bits will not inhibit the assigning of a LUNO to a sequential, 
relative record, or key indexed file. 


Delete File (9216) 


This operation deletes the file whose pathname is addressed by the path- 
name in bytes 22, 23 if no LUNOs are assigned to the file. 


Release LUNO (93 16) 


Disassociates a LUNO from a file. User needs to specify: 


byte 3 - LUNO 
byte 16 - scope of LUNO in bits 3, 4 


This call only releases a LUNO on the level indicated within byte 16, 
For example, if the call is “release a terminal LUNO 88" and there is 
none, but there is global LUNO 88 ond a task local LUNO 88, neither 
will be released, i 
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5.5.6 


5.5.7 
5.5.8 


5.5.9 


5.5.10 


5.5.11 
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Define Write Mode (9C 4) 


This call defines (or changes) the write mode of a file, User needs to 
specify: 


byte 3 - LUNO assigned to file that is to have the write mode defined. 
byte 17 - write mode as defined 

if bit 2 = 1 disk writes are to be done immediately 

if bit 2 = 0 defer writes to disk 


This call changes the write mode only for the specified LUNO assignment; 
file characteristics do not change. 


Renome_ (95), ) 


This call assigns a new nome to a file, User needs to specify: 


byte 3 - LUNO of file to be renamed 
bytes 22, 23 - pathname pointer; the indicated pathnome is taken as the 
“new name. ’ 


If a file already exists with the new name, the renome operation deletes 
the previous file before assigning the new name to be specified file. The 
user may set the 'Do Not Replace’ user flog (byte 5 bit 5 of the call 
block) to prevent deleting the previous file and abort the renome ope- 
ration, No other LUNOs may be assigned to either file. If the destina- 
tion file already exists, the aliases are retained. 


Unprotected File (96 16) 


This opcode disables write and delete protection for a file. 


Write Protect File (9714 ) 


This opcode enables write protection for a file. 


Delete Protect File (9816) 


This opcode enables delete protection for a file, 


For th se three operations (96 , 97 , 98 ), only the pathname pointer 
is necessary. No LUNOs may be assigned to the file. 


Verify Poathname (99 19) 


This opcode does a syntax check of a pathnome by attempting to assign a 
LUNO to the file, Only bytes 22, 23 (pathname pointer) need to be given. 
If the pathnome is really a file and it exists, the file usage, file 
type, data format, and allocation type are returned in bytes 16 and 17, 


Add Alias (9A 16) 


This opcode assigns an "alias" (i.e., an alternate nome) to a file. 
User needs to specify: 


byte 3: LUNO assigned to the file. 
bytes 22, 23: pointer to pathname (the olias) 
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5.5.12 Delete Alias (9B, ) 


This opcode deletes an "alias". 


NOTE : 
Alias can differ from ordinary name only in rightmost component. 


Example: nome = a.b.c 
valid alias = a,b.d 
invalid alias = b.i.d 


5.6 Temporary Files 


The use of temporary files and avtocreate allows a program to process 
an input file, generate a temporary file, and at the end of the progrom 
replace the input file with the temporary file. Necessary steps to ac- 
complish this are: 


@ e Create the temporary file using assign LUNO (opcode 91,, ) and 
specify: 


GENERATE LUNO 

AUTOMATIC CREATE 

TEMPORARY FILE 

Pathnome address equal to zero. 


e Write data to the temporary file using the LUNO returned by TAXO. 
Close the temporary file. 


e Renome the temporary file using the Rename operation (opcode 9514) and 
for a nome specify the input file file nome. This will delete the in- 
put file replacing it with the temporary file using the some nome as 
the deleted input file. 


e Release the |UNO, 


This method bypasses copying the temporary file to the input file and 

does not require naming the temporary file, TAXO automotically deletes 

temporary files created in this manner when the system is warm started 

to relieve the operator from the duty of deleting intermediote files 
& which remain after a progrom crash or other problem. 


im 


@ 
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6 PRIVILEGED SUPERVISOR CALLS 


6.1 General 


Privileged SVCs may only'be issued by privileged or system tasks. Tasks 
are specified as privileged or system at task installation time, These 
SVCs are privileged because their misuse can either destroy the system 
(e.g., by irrevocably and improperly modifying the disk) or hoard the 
system (e.g. by killing other tasks), The following porographs describe 
the SVCs, what they do, and how they ore used. For the examples of SVC 
calls, assume that this instruction has been assembled: 


DXOP = SVC, 15 DEFINE SVC AS XOP 15, 


All of the call blocks should start on a word boundary, Error codes re- 
turned by SVC processors ore described in Error Monval. 


6.2 Instell Task (Code 2515) 


This SVC is used to install an object module, supplied on a given file 
or device, in the specified program file. 


NOTE 

The user should not install a task on the SSPROGA, SSSDSS and 
TASPROG program files, If on of these progrom files is used, the 
user's IDs and nomes will be destroyed upon each new release of 
TAXO, It is recommended that the user instoll tasks in his own 
library, This recommendation also applies to installing real- 
time tasks, procedures, and overlays. 


Svc CODE ERROR CODE 


TASK NAME 


PROC 1 ID 


is RESERVED (<0) 


Byte 


4-11 


12 


13 
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Description 
SVC code (= 2514) 
Error code returned by TAXO. 


LUNO assigned to the program file on which the tosk is to be in- 
stalled, If 0, the system program file is assumed. This LUNO 
must be closed, except for the special form used by the Link 
Editor and other system utilities (see para. 6.2.1). 


Optional task ID. If 0, an available ID is assigned, and retur- 
ned in this byte. Appendix A contains a list of IDs reserved 
for system tasks on the system progrom file. Tasks which are to 
be installed on the system program file may not be assigned one 
of those IDs, 


Task name, up to eight ASCII characters left justified with 
trailing blanks, The task name must be unique within each pro- 
grom file. If this field is binary 0, the IDT from the object 
module name will be used and returned in this field. 


Flags: 
Bit 0 - Privileged Task 
Bit 1 ~- System Task (is mopped into system memory in addi- 


tion to being privileged) 


Bit 2 - Memory-Resident Task, Must be installed on the sys- 
tem progrom file, The task will be executed as a 
disk resident task until the system is booted. 


Bit 3 - Delete protected, The task cannot be deleted until 
the delete protect bit is set to zero. 


Bit 4 - Replicative., Copies of this task may be created and 
may execute concurrently, shoring procedures. 


Bit 5, 6 - Associated with procedure 1 and 2 respectively. If 0, 
the procedure is to be looded from the same program 
file as the task, If 1, the procedure is to be loaded 
from the system progrom file. 


Bit 7 - Has special usage to support the Link Editor, Editor, 
if 1 (see para, 6.2.1). Normally 0. 


Priority. May be 0-4 or Real-time 1-127, Priorities 0-3 corres- 
pond to the task's execution priority level and are fixed, while 
priority 4 indicates that the priority level is to be dynamically 
managed by the operating system. The highest priority level is 0, 
while 3 is the lowest. Operating system tosks are assigned prio- 
rity O and 1, Critical system tasks are assigned the priority 

of 0. Priority 0 should be considered reserved for operating 
system use exclusively. Real-time priorities 1-127 logically 

fall between priority 0 and-] and are indicated by setting the 
most significant bit of the byte. 
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Byte :.. . 


14 
15 
16 


17 


18-19 
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Description 


If priority 4 is specified, the task priority is managed by the 
system when the task is bid. The task’s priority is dependent 
upon its execution mode. If the porent task (i.e., the task 
which issues the Bid Task SVC) is also installed with ao prio- 
rity of 4, then the bid task is considered to be executing in 

a "foreground" mode (not the same as SCI foreground). If the 
parent task does not have a 4 priority, the bid task is consi- 
dered to be executing in the “background” mode, and is assigned 
o priority of 3, in order not to degrade the response of "fore- 
ground" tasks. 


A "foreground" task initially executes at priority 1. Thereafter, 
each time the task executes a minimum number of time slices for 
its priority level the priority level is lowered by one. When 
the task suspends for terminal input, it is reassigned priority 
level 1, If it suspends for any other non-TILINE 1/0, it is 
assigned priority level 2 (unless the task already has a prio- 
rity of 1). TILINE I/0 does not change the. priority. Whenever 
the task does terminal input, its priority will be 1. 


Procedure 1 ID,.A zero value indicates no procedure. 
Procedure 2 ID, A zero value indicates no procedure. 


LUNO assigned to the object file from which the task object 
code is to be read. This LUNO must not be open, 


Flags: ; 

Bit O - Overflow. If crithmetic overflow occurs with this 
bit set to one, control will be passed to the task’'s 
end action routine. 

Bit 1 - Writable Control Storage. If the task uses a writable 
control storage area, this bit must be set to one. 

Bit 2 - Execute Protected. If the task is to be execute 


protected, this bit must be set to one. 
Bits 3-7 - Unused. Must be set to zero. 


Reserved, Initialize to zero. 


6.2.1 


6.2.2 
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Somple code to install a privileged task on the system progrom file: 


EVEN 
BLOCK BYTE >25 SVC CODE FOR INSTALL TASK 

BYTE 0 RESERVED FOR RETURNED ERROR CODE 

BYTE 0 PUT THIS TASK ON THE SYSTEM FILE 

BYTE >83 ASSIGN ID >83 TO THIS TASK 

TEXT ‘MYTASK ‘TASK NAME 

BYTE >88 MAKE THIS TASK PRIVILEGED AND REPLICATABLE 

BYTE 2 PRIORITY 2 : : 

DATA 0 NO PROCEDURES 

BYTE >4A OBJECT FILE IS LUNO >4A 

BYTE 0 RESERVED, INITIALIZE TO 0 


DATA 0 RESERVED, INITIALIZE TO 0 


INSTAL SVC GBLOCK 


Special Form of Install . 

Flag bit 7 is used to indicate thot this is a specicl install operation. 
The bit, when set, indicates that the imoge for the program segment has 
already been written to the progrom file. This form of the Install SVC 
is used by the Link Editor in image mode to update the progrom file di- 
rectory entry for the program segment. For this operation the object 
LUNO is not referenced. The Link Editor uses this SVC in conjunction 
with SVC 37. (used to get space on the program file). The program file 
should be opened for exclusive write occess privileges before executing 
the Install SVC, The following additional information must be specified 
for the special Install SVC: 


Byte Description 

18-19 Load address. 

20-21 Length of task root and longest overlay path. 
22-23 Length of task rodt. 


Install Real-Time Task 


To install a task as a real-time task, the SVC must be set up the some 
as for INSTALL TASK except for the priority byte, byte 13, The first bit 
if byte 13 must be set to one and the remaining seven bits must contain 
a value between one and 127 inclusive. The highest real-time priority is 
one and the lowest is 127, Refer to the NOTE in paragraph 6.2. 
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6.3 Install Procedure (Code 264) 


This SVC is used to install an object module from a given file or device 
(LUNO) as a procedure in a specified progrom file. Refer to the NOTE in 

paragraph 6.2, The install procedure SVC block is similar to the install 
task block and has the following format: , 


Byte 


4-11 


12 


RETURNED ERROR CODE 


PROCEDURE NAME 


FLAGS OBJLUNO 
RESERVED (=0) 


Description 
SVC code (26, ). 
Error code returned by TAXO, 


LUNO of program file on which procedure is to be installed. If 
0, the system progrom file is assumed. This LUNO must not be 
open except for the speciol install function (see para. 6.3.1). 


Procedure ID. If 0, the system will assign an ID and return it 
in this byte. 

Procedure nome, up to eight ASCII characters with trailing 
blanks. The procedure name must be unique in each program file. 
If this field is binary 0, the IDT name from the ansect module 
is used, 


Flogs, which when set mean: eM 4 
Bit 0-1 - Not used, must be set to 0. - ee 
Bit 2 - Memory resident, The procedure must be installed on e 


the system program file, and will not become memory 
resident until the system is rebooted, 

Bit 3 - Delete Protected, The procedure cannot be deleted | 
until this bit is reset. 

Bit 4 - Writoble Control Storage. If the procedure uses.a 
writable control storage, this list must be set = 
to one, ve 
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Byte Description 


Bit 5 - Execute Protected. If the procedure is to be execute 
| protected, this bit must be set to one. 
Bit 6 - Write Protected. If the procedure is to be write 
protected, this bit must be set to one. 
Bit 7 - Normally 0. Has special system usage if 1 to sup- 
port the Link Editor (see para, 6.2.1). 
13 LUNO assigned to the file from which the object module is to be 


read, This LUNO must not be open. 
14-15 Reserved, Initialize to zero, 


The following is somple code to install a procedure: 


EVEN 
BLOCK BYTE >26 * INSTALL PROCEDURE SVC CODE 
BYTE 0 ERROR CODE 
BYTE >AA PUT THE PROCEDURE ON THE FILE DESIGNATED 
BY LUNO 
‘ - DAA. 
BYTE 0 LET THE SYSTEM ASSIGN AN ID 
TEXT ‘MYPROC * PROCEDURE NAME 
BYTE 0 NO SPECIAL FLAGS 
BYTE >BB THE OBJECT MODULE IS ON FILE >BB 


DATA 0 RESERVED 
INSTAL SVC @BLOCK INSTALL THE PROCEDURE 


6.3.1 Special Form of Install Procedure 
If flag 7 is set, the following bytes of information must be added (see 
para, 6.2.1 for a complete description): 


Byte | Description 
14-15 Load address, — 
16-17 Length of procedure in bytes 
18-19 Reserved. Initialize to 0, 
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6.4 Install Overlay (Code 274) 


This SVC is used to install an object module from a given file or device 
as an overlay in the specified program file. Refer to the NOTE in paro- 
groph 6.2, The call block is similar to the install task call block, 

and has the following format: 


Byte 


4-11 


12 


RE TURNED ERROR CODE 


OVERLAY NAME 


ai te eu 


Description . | 
SVC code (27,, ). 
Error code returned by TAXO, 


LUNO of program file on which overlay is to be installed. If 0, 
the system program file is used. This LUNO must not be open ex- 
cept for the special install function (see para. 6.4.1). 


Overlay ID, If 0, the system will assign an ID and return it in 
this byte. 


Overlay nome, The overlay name must be unique in the progrom file. 
If this field is binary 0, the IDT name from the object file is 
used, and returned in this field. 


Flags: 

Bit O - Relocatable, 

Bit 1-2 - Not used, must be 0. 

Bit 3 - Delete protected, The overlay cannot be deleted un- 


til this bit is reset. 

Bit 4-6 - Not used, must be 0, 

Bit 7 - Normally 0. Same as for install task and procedure 
(see para. 6.4.1). 
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Byte Description 


13 Associated task ID. If specified, the overlay must have been 
installed on the some program file as the task, and is automa- 
tically deleted when the'task is deleted. 


14 LUNO assigned to the file from which the object module is to be 
read, This LUNO must not be open. 


15-17 Reserved, Initialize to zero. 


The following code is an example of the call block and coll. 


EVEN 
LAYLA BYTE >27 INSTALL OVERLAY CODE 
BYTE 0 RESERVED FOR ERRORCODE 
BYTE 0 INSTALL THIS ON THE SYSTEM FILE 
BYTE 0 LET SYSTEM ASSIGN ID 
TEXT ‘OLAY! ‘OVERLAY NAME 
BYTE >80 RELOCATABLE 
BYTE >83 ASSOCIATE WITH TASK >83 
BYTE >0A GET OVERLAY FROM LUNO >0A 
BYTE 0 RESERVED 


DATA 0 RESERVED 


CALL SVC @LAYLA INSTALL THE OVERLAY 


Special Form of Install Overlay 


If flag bit 7 is set, the information added is the same as for install 
task or procedure (see para, 6.2.1), that is: 


Byte Description 
16-17 Load address 
18-19 Length of overlay in bytes 


20-21 Reserved, Initiolize to zero. 


6.5 Delete Task (Code 2814) 


The Delete Task SVC is used to delete the task with the specified ID from 
the given program file, All associated overlays are automatically deleted. 
The call block is six bytes in length, and has the following format: 


aed % 


ae pe 


ee 3 ; 
FLAGS ° RESERVED (=0) 


lamitse 
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Byte Description 


0 SVC code (28,,). 


Error code returned by TAXO. 


2 LUNO assigned to the program file from which the task is to be 
deleted. Deletion of delete protected tasks is not allowed. 
This LUNO must not be open, unless flog bit 7 is set. 


3 ID of task to be deleted. 
Flags, which when set mean: 


bits 0-6 - Not used, must be zero. 
bit 7 - Program file is open. 


a Reserved, Initiolize to zero, 


The following sample code deletes task 83,,, which was installed on the 
progrom file assigned to LUNO 4A,,. 


EVEN 

DELETE BYTE >28 SVC CODE 
BYTE 0 RESERVED FOR ERROR CODE 
BYTE >4A THE TASK IS ON LUNO >4A 
BYTE >83 THE TASK ID IS >83 


DATA 0 RESERVED 


DELTSK SVC  GDELETE 


Delete Procedure (Code 294) 


This SVC is used to delete the specified procedure from the given program 
file, The format and contents of the call block are the same as for de- 
lete task, except that the ID in byte 3 is the procedure ID, 


Delete Overlay (Code 2Ai6) 


This SVC is used to delete the specified overlay from the given program 
file. The format and contents of the call block are the some as for de- 
lete task (see para. 6.5), except that the ID in byte 3 is the overlay 
ID. 


Kill Task (Code 3314) 


The Kill Task SVC is issued by one task in order to terminate another 
running task. The call block is eight bytes and has the following format: 


sve CODE ERROR CODE 
STATE RESERVED (=0) 
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Byte Description 


0 SVC code (33), he 
Error code returned by TAXO. 
2 Runtime ID of the task to be terminated. Note that the runtime 


ID of a task may be different from the installed ID, if the 
task is replicatoble, becuase the system chooses on ID for 
task replicas. 


3 Optional station ID. If this byte is: 
i 0 - Any running task with the specified ID will be ter- 
i minated. 
: 1-FE,, - The task must be associated with this station num- 
j ber in order to be terminated. 
{ FF,, - The task to be terminated must not be associated 


with o station. 


wat oe, 


& 4 The state of the task at terminction is returned in this byte. 


5-7 Reserved, Initialize to zero. 


The following is on exomple of code for killing a task: 


EVEN 
KILL BYTE >33 SVC CODE FOR KILL TASK 
BYTE 0 ERROR CODE 
BYTE >83 KILL TASK >83 
BYTE 0 KILL ANY TASK WITH RUN ID >83 
BYTE 0 RETURN TASK >83 STATE HERE 
BYTE 0 RESERVED 
0 RESERVED 


DATA 


KILTSK SVC @KILL 


6.9 Suspend Awaiting Queve Input (Code 2414) 


This is a special SVC used by queve serving tasks. When a queve server 
& has processed all the entries in its queve, it issues a code 24,, SVC 
to suspend itself until another entry is put on the queve. 


For a queve serving task this SVC serves the some purpose as on End Pro- 
gram SVC for a normal task, except that the suspended queve server is not 
processed by the termination task; therefore, any task local LUNO's must. 
be released before this SVC is issued. The queve server is not rolled 
when it suspends for queve input, but will be released from memory only 
when it is chosen for rollout by task management. The call block is one 
byte, which contains the SVC code: 


al 


ee 


{ _. *THIS IS SAMPLE CODE FOR A SUSPEND 
*AWAITING QUEUE INPUT SVC 


SAQI BYTE 24 THIS IS THE CALL BLOCK 


oUT svc GSAQI THIS IS THE CALL 
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6.10 Read/Write TSB (Code 2C 4) 


This SVC is used to read/write one word of data from/to the specified 
task's task status block and should be used with extreme caution. Some 
fields of a TSB cannot bé modified without serious impact on the opera- 
ting system, No protection is provided to prevent the use of this SVC 
from causing a system crash, Note that the use of this SVC assumes a 
TSB format which may be changed as new system requirements are imple- 
mented. 


The logical sequence for using the Read/Write TSB supervisor call is: 
1, Extend the time slice 

2. Read TSB 

3. Write TSB 

The coll block formot is: 


DISPLACEMENT 


Byte Description 

0 SVC code (2C 14) 

1 Error code returned by TAXO. 
2-3 Flags: 


Bits 0-14 ~ Not used. Initialize to 0. 
Bit 15 - 1 for write. 


O for read. 
Runtime ID of the task whose TSB is to be read/written. 
5 Byte offset into the TSB of the word to be read/written 
(should be even). 
6-7 Value of the word read/written. 
8-9 Reserved. Initialize to zero. 


‘EL aay: 
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The following code is an example of a code 2C,, SVC: 


“THIS ROUTINE WILL ALLOW TASK 83 TO TAKE END ACTION AGAIN. 


RWTTSB 
SVCFLG 


VALUE 


MEMRES 
WRTFLG 
EXTEND 


EVEN 
BYTE 
BYTE 
DATA 
BYTE 
BYTE 
DATA 
DATA 
DATA 
DATA 
BYTE 


svc 
SvC 
SOC 
MOV 
SVC 


J 


>2C THE SVC CODE 

0 RESERVED FOR ERROR CODE 

0 FLAGS 0 = READ, | = WRITE 

>83 TSB OF TASK >83 

10 THE DISPLACEMENT OF THE TASK FLAGS IN TSB. 
O° RESERVED FOR VALUE RETURNED 

0 RESERVED 

>1000 END ACTION FLAG MASK 

| WRITE TSB FLAG 

9,4 EXTEND TIME SLICE 4 SYSTEM TIME UNITS 
@EXTEND EXTEND TIME SLICE 

@RWTTSB READ THE CURRENT TSB WORD 


@MEMRES, @VALUE RESET END ACTION 
@WRTFLG, @SVCFLG SET WRITE FLAG IN BLOCK 
@RWTTSB WRITE THE TSB WORD. 


6.11 Read/Write Task (Code 2D, ) 


This SVC is used to read/write up to 16 words of data from/to the speci- 
fied address in the designated task. The task must be either in memory 

or in on unconditionally suspended state (this can be forced by halting 
the task). The call block is 40 bytes long and has the following format: 


SvC CODE ERROR CODE 


eg 


Bytes 


4-5 


6-37 


@ 38-39 
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Description 
SVC code (2D,,). 
Error code returned by TAXO. 


Runtime ID of task to be read/written. A zero value indicates 
that the TAXO system root is to be read/written. 


Flags: 
Bit 8 - O for read, 1 for write, 
Bit 9 - 0 = Task ID, 1 = System Overlay Segment ID 


Bit 10-11 - Reserved, Initialize to zero. 
Bit 12-15 - Number of words (a zero value specifies 16 words) 


Relative address in the specified task of the first word of the 
data block, 


16 word data block, 


Reserved. Initialize to zero. 


The following code is an exomple of a Read Task SVC: 


*THIS ROUTINES READS THE WORKSPACE OF TASK >83, 
* 


ASSUMING THAT THE WORKSPACE ADDRESS IS 6, 
AND THAT THE TASK IS MEMORY RESIDENT. 


EVEN 
RDTSK BYTE >20D SVC CODE 
: BYTE 0 RETURNED ERROR CODE 
BYTE >83 READ/WRITE FROM TASK >83 
BYTE 0 READ 16 WORDS 
DATA 6 ADDRESS OF WORKSPACE 
DATA — BSS 32 16 WORD BUFFER 


DATA 0 RESERVED 


SVC “RDTSK READ THE WORKSPACE 


& 6.12 Get System Pointer Toble Address (Code 32 


This SVC is not a privileged supervisor call, but it is only useful to 


privileged or system tasks. The SVC returns the memory address of a 
table of pointers to various system routines and dato structures. The 
table is used by disk-resident system tasks and overlays to provide 
run-time linkage with the operating system, The call block is six bytes 
- long and has the following format: 
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Byte Description 


0 SVC code (32,,). 

1 Error code returned by TAXO, 
2-3 Address return field. 

4-5 Reserved, Initiclize to zero. 


The following code is an example of the Get System Pointer Table SVC: 


EVEN 
GSPTA BYTE >32 SVCCODE 
BYTE 0 ERROR CODE 
DATA 0 ADDRESS RETURN FIELD 
0 RESERVED 


SVC @GSPTA GET SYSTEM POINTER TABLE ADDRESS 


Initialize Date and Time (Code 3B), ) 


This SVC stores the date and time information given in the specified 
block, , 


The 6-byte call block has the following format: 


| sve cone ERROR CODE 
DATE/TIME BLOCK ADDRESS 


The SVC code, error code, and reserved bytes have the same use as in 
preceding SVC descriptions, Bytes 2-3 contain the address of a block of 
data which contains the date and time. The data block is a 6-word block 
of the form: 


BYTE 


YEAR 
” MINUTE 
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Each data word should be a binary value. The following is an exomple of 
on Initialize Dota and Time SVC: 


EVEN 3 
IDATIM BYTE >3B SVC CODE : 
BYTE 0 ERROR CODE 
DATA BLOCK ADDRESS OF DATA BLOCK 
DATA 0O RESERVED 
BLOCK DATA 1977 YEAR (1977) 
DATA 84 : DAY (MARCH 25) 
DATA 8 HOUR (8 A.M.) 
DATA 3 MINUTE (8:03) 
DATA 15 SECOND (8:03:15) 


DATA 0 RESERVED 


@ SVC. @IDATIM 


6.14 Disk Manoger (Code 2215) 


This SVC calls the disk manager. The disk manager allocates and deallo- 
cates disk space in allocable disk units. Allocable disk units (ADUs) 
are used by TAXO strictly for allocating and deallocating disk space. 

An ADU is an integer number of sectors on the disk, and is defined to 
be the smallest omount of disk storage which can be allocated by the 
disk manager. An ADU is defined such that the maximum number of ADUs 
per disk is less than 65536 (i.e., any ADU may be addressed in a 16-bit 
word), Since different disk types vary in the number of sectors (and the 
amount of information) they contain, ADU size varies between disks, 
Table 6-1 shows the ADU sizes on disks supported by TAXO. 


Table 6-1. Disk Descriptions 
Disk Type No. of Sectors No. of ADUs Sectors/ADU Bytes/ADU 
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When the disk manager is called, via SVC code 22,,, the calling task is 
suspended and made eligible for rollovt. The call block has the follow- 
ing format: 


J 
Svc CODE ERROR CODE 
DISK PDT ADDRESS 
BLOCK SIZE (BYTES) 


MAXIMUM NO, OF BLOCKS 


Description. 
SVC code (22,, ). 
Error code returned by TAXO. 


Opcode: 

0 = Deallocate 

1 = Allocate the whole area or fail 

2 = Allocate as much as possible 

3 = Allocate as much os possible where requested or fail 


Reserved. Initialize to zero. 


Physical device toble address of the disk unit on which space 
is to be allocated/deallocoted. 


Size of blocks to be allocated, in bytes. Ignored for deallocation. 


Maximum number of blocks to be allocated, Bytes 8-9 ignored for 
deallocation, 10-11 is number of ADUs to deallocate. 


If deallocating: starting ADU of area to be released. 

If allocating: try to allocate as close to this ADU as possible; 
if the value is 0 and the opcode is 1 or 2, the lowest area is 
allocoted. 


Note that specifying the area to be allocated in blocks, and a block size 
given in bytes, mokes it unnecessary for the caller to know the disk 
format. Allocations are made in terms of ADUs since file allocation 
tables within TAXO are kept in terms of ADUs. 


1630/SVC/SC1/0281/e 


6/17 


In addition to the error code, the disk manager returns allocation in- 
formation if the opcode was a 1, 2, or 3. The returned information is 
placed in the call block as shown: 


BYTE 
ae ae 
7 Cicer 
/ nes: See 
SI ne an 
ee 
. 
NOT CHANGED FROM INPUT VALUES 
Byte Description 
0 Not changed 
1 Error returned by TAXO. 
2-7 Not changed 
8 Number of ADUs per block (block size specified in call). Set to 
1 if less then 1. 
9 Number of block per ADU. Set to 0 if less than 1, 


10-11 Number of -ADUs allocated. 
12-13 ADU number of the first ADU in the allocated area, 


_ The disk manager allocation algorithm is designed to reduce head movement 


‘and fragmentation of files and disk space. The priorities used when allo- 
cating disk space are: 


*1, Start at requested ADU (coalesce disk space) 


' *2, Size requested 


3, Proximity to requested ADU (reduce head movement) 
4, Lower ADU first (reduce fragmentation of disk space) 


“Priority for opcodes 2, 3; reserved for opcode 1. 
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The following is an example of a disk manager call to allocate: 


EVEN 
DSCMGR BYTE >22 SVC CODE ; 
ERRCOD BYTE 0 ERROR CODE 
BYTE 2 ALLOCATE AS MUCH AS POSSIBLE 
BYTE 0 RESERVED 
DATA DPDT DISK PDT ADDRESS 
DATA 128 128-BYTE BLOCKS 
APBPA DATA 0 NEED 64 
SIZE DATA 64 BLOCKS : 
START DATA 0 ALLOCATE AS LOW AS POSSIBLE 


SVC @DSCMGR 


6.15 Assign Space _on Program File (Code 371.) 


a This SVC is used by the link editor and other system utilities, The call 
assigns a starting record on the specified program file, to be loaded 
with a task, procedure, or overlay image. The call block has the follow- 


ing form: 
| sve cone | emon cone 
a ee 


Byte Description 


@ re) SVC code (37,, ) 
1 Error code returned by TAXO, 
2 LUNO assigned to the program file. The LUNO should have been 
opened with exclusive write occess by the calling task. 
3. Reserved. Initialize to zero. .,. 
4-5 The length in bytes of the image to be written. 
6-7 Returned record number which begins the area allocated on the 
program file. 
8-9 Reserved. Initialize to zero. 


ee oA op 

: fener OE be, 
H Peas. 
A a 
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SVC: 
EVEN 
ASOPF BYTE >3) SVC CODE 
ERRCOD BYTE 0 ERROR CODE 
BYTE PFLUN LUNO OF THE PROGRAM FILE 
BYTE 0 RESERVED 
DATA 100 NEED 100 BYTES 
RECORD DATA 0 RESERVED FOR RETURNED RECORD # © 


DATA 0 RESERVED 


SVC @ASOPF 


6. 16. Initialize New Volume (Code 38 16) 


' This SVC is used to initialize a new disk volume, It also installs the 
volume (see paragraph 6.17). The Initialize New Volume SVC performs the 
following functions: 


e Formats all tracks on the disk one sector per record 
e@ Builds Track 0, Sector 0 (special volume overhead) 

e Builds the bad ADU list on Track 0, Sector 1 
° 


Builds the ADU availability portial bit maps which fill the remainder 
of Track 0 


Builds the volume directory on the disk 


Installs the new volume by issuing an Install Volume SVC (see paro- 
graph 6.17). 


The call block has the following format: 


DISK DRIVE NAME 
(4 ASCII CHARACTERS) 


VOLUME NAME 
(8 ASCItl CHARACTERS) 


(weenie [Oe 


TRACK NUMBER 1! 
LOADER LUNO RESERVED 0 


BY TE 
i] 


7 


18 


22 
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Description 

SVC Code (38,, ) 

Returned error code : 

Device name of disk unit (e.g., DSO2, DSO3) 
Name of volume to be initialized 


Number of entries to be included in the volume directory. (If 
equal to zero, 360,, is assumed). 


LUNO assigned to a file which contains a list of the bad tracks 
for the new disk. The form of the list is as follows: 


HEAD CYLINDER; 
OR 
HEAD, CYLINDER; HEAD, CYLINDER; etc. 


The last entry in the list, need not be followed by a semicolon. 
The list is terminated by an empty line. A zero in this field 
implies not list is present. 


Flogs 

00 Use the loader on the system disk. 

80 No loader will be placed on trock #1 (i.e., VCATALOG 
starts on Track #1, Sector #0). 

co Byte 22 identifies track #1 loader. 


Default physical record size used in VCATALOG for subsequent 
file creation. If the value is. zero, the defavlt physical re- 
cord size is taken from the sysgen porometer for that disk drive. 


Hardwore interleaving factor used to format the sectors of the 
disk, The value must be N; Oc N< (number of sectors per track 
-2). If N=O, a value of 1 is assumed (this spplies only to 
double density dual sided diskettes). 


LUNO assigned to an image file that is to be placed on track #1, 
The first word of the file is assumed to be an entry point and 
is placed in track #0, sector £0, byte £18,,. Byte 17 must con- 
tain CO,, for this option. 


The following is an erate of an Initialize New Volume SVC: 


EVEN 
INIUT BYTE >38 SVC CODE 

BYTE RETURN ERROR CODE 

TEXT ‘DSO04’ DEVICE NAME 

TEXT ‘NEWVOLbb’ VOLUME NAME 

DATA 20 20 ENTRIES IN 
VOLUME DIRECTORY 

BYTE BTLLUN BAD TRACK LIST LUNO 

BYTE >C€O FLAGS (BYTE 22 CONTAINS 
TRACK #1] LUNO) 

DATA 0 DEFAULT PHYSICAL 
RECORD SIZE (864 is implied) 

DATA 0 HARDWARE INTERLEAVING 
(1 is implied) 

BYTE LDRLUN LUNO FOR TRACK #1 
LOADER 


BYTE 0 RESERVED (must be zero) 
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The Install Volume SVC must be used in order to make a disk volume 


availoble for file storage. The Install Volume SVC performs the follow- 
ing functions: y 


e Verifies that the given volume nome matches the disk drive specified 
e Verifies that the specified drive is available 

e Builds the file control block for the volume directory 

e Initializes memory to be used by the disk manoger 

e@ Deletes any temporary files on the disk 


The call block is the some as the first 14 bytes of the Initialize Vo- 
lume SVC, and has the following format: 


DISK §D (4 ASCII CHARACTERS) 


VOLUME NAME 
(8 ASCII CHARACTERS) 


“Byte Description 


0 SVC code (20,,) 

1 Returned error code 

2-5 Disk device nome (e.g., DSO1, DSO3) 

6-13 Name of volume to be installed. If another volume is installed 


on the disk drive, the installed volume nome is returned in - 
this field, and byte 1 will-contain on error code. 


The following code is an example of an Install Volume SVC: 


sth 


- EVEN ae 
INSVOL .BYTE >20 SVC CODE 

BYTE 0 RETURNED ERROR CODE 

TEXT ‘DSO2’ DISK UNIT 02 


TEXT ‘NEWVOL * VOLUME TO BE INSTALLED 
. id 


svc @INSVOL INSTALL THE VOLUME 
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6.18 Unload Disk Volume (Code 3416) 


This supervisor call is used to unload a volume which is no longer 
being used, usually with the intent, of installing a new volume on the 
disk drive. The Unload Volume SVC performs: the following functions: 


e Determines the device on which the specified volume is installed 
e Verifies that no LUNOs are assigned to files in this volume 

e Releases all memory allocated to support this volume 

e Updates the disk PDT to show that the volume is unloaded 

e Returns the physical device name 


The 14-byte call block has the some format as the Install Volume SVC, 
except that the disk ID in bytes 2-5 is returned by the system. The 
following is an example of an Unload Volume SVC: 


EVEN 
UNLVOL BYTE >34 SVC CODE 

BYTE 0 RETURNED ERROR CODE 
DISKID BSS 4 RETURNED DISK ID 


TEXT ‘OLDVOL * VOLUME TO BE UNLOADED 


Direct Disk I/O 


In order to maintain disk file integrity and security, and to control 
disk allocation, direct disk (or diskette) I/0 is reserved for use by 
privileged or system tasks, which have direct and global access to disk 
units. 


I/O to disk or diskette is controlled by an extended call block as des- 
cribed in paragraph 6.19.1. As with ony other device, access is through 
a LUNO assigned to the disk. TAXO has o reserved system (non-releasable) 
LUNO for each disk unit configured in the system. Action taken on the 
standard I/0 opcodes for disk is described in paragraph 6.19.2, while 
diskette I/0 is described in paragraph 6.19.3, Disks and diskettes are 
classified os record oriented devices by TAXO ond need not be opened 
before 1/0 operations:.or closed afterward. 


Before tracks on a disk cartridge or a diskette can be used for data 
storage, they must be formatted. That is, the physical record length 

of the records on a track must be defined on the disk pack. This is 

done when a system disk is built or when a secondary disk is initialized 
(see para, 6.16, Initialize New Volume). The actual physical organiza- 
tion of a disk pack is by heads (recording surfaces), cylinders (record- 
ing bands on all surfaces), and sectors (timing marks dividing each cy- 
linder). A track is one surface of a cylinder and is the smallest unit 
which can be idependently formatted. Tracks are addressed by the expres- 
sion: c*H+h=T where 


T is the addressed track number 

H is the number of heads for the disk unit 
c is the addressed cylinder number 

h is the addressed head 


Figure 6-1 shows the manner by which tracks are addressed. 
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CYLINDERS 


TRACK X AODRESS <« Sobinver ® TOTAL HEADS + ADDRESSED HEAD 
= »6@+5 
= 21 


ss 
Figure 6-1, Addressing a Track 


Track addressing runs sequentially from zero to the maximum track address. 
Each track is formatted for a given physical record length (a physical 
record is the smallest unit of data transfer from the disk) with result- 
ing records per track and sectors per record, Physical records must 

start at sector boundaries but need not fill entire sectors ond may cross 
sector (but not track) boundaries. Each record defined on a track requires 
a fixed omount of overhead, thus the larger the records, the fewer records 
per track, the less overhead required, resulting in more usable bytes per 
formatted track, Note that all disks initialized under TAXO V100 (using 
the Initialize Volume command or SVC) are formatted one sector per phy- 
sical record. 


WARNING , 
Reformatting a track after the disk has been initialized for TAXO Be: 
use will destroy any data that is on the specified track. Also, Ls 
if the format is not one SECTOR/RECORD, TAXO will not be able to rs 


access that track except through user direct disk I/O. 


fle ay 


ow 
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6.19.1 Direct Disk 1/0 Call Block 


The supervisor coll block used for the Direct Disk 1/0 SVC is the same 
os a normal 1/0 call block, with a two-word extension used to contain 
a disk address. The call block has the following format: 


ee ee 


BUFFER ADDRESS 
RECORD LENGTH 
CHARACTER COUNT 


TRACK ADDRESS 
SECTORS/RECORD SECTOR NO, 


STANDARD 
CALL BLOCK 


OR . UNIQUE TO 
DISK t/O 


SECTOR OFFSET IN ADU 


_ supports addressing by ADU/Sector offset or Track/Sector 
offset on disk units, 

Byte Description 

0 SVC code (0). 

1 Error code returned by TAXO, 

2 + I/O opcode (see para. 6,19.2 and 6.19.3). 

3 LUNO assigned to the disk. 


6.19.2 
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Byte Description 


4 Flags set by the system - when set mean: 
Bit O - LUNO'is busy 
Bit 1 - Error 
Bit 2 - End of file condition (not applicable) 
Bits .~ Reserved 
5 Flags set by user - when set mean: 


Bit 8 - Initiate 1/0 
Bits 9-15 - Reserved (set to 0) 


6-7 The address of the buffer to which data is to be read or from 
which data is to be written. Must begin on a word boundary. 
8-9 “The length in bytes of a physical record, This number deter- 


mines the maximum number of bytes transferred during o read. 
Must be an even count. 


10-11 The number of characters to be written. Must be an even count. 
TAXO returns the number of characters read by a read operation 
in these bytes, 


The last two words of the call block vary occording to the addressing 
mode of the 1/0 operation. If the address of the logical record is given 
as track and sector, then: 


Byte Description 


12-13 The track number in which the record is located (see fig. 6-1 
for track addressing). 


14 The number of sectors per physical record. 

15 The starting sector number of the record. 

If the address is given as ADU/sector offset, then: 

Byte Description 

12-13 The ADU number in which the physical record starts, 


14-15 The starting sector number of the physical record within the ADU, 
This must be specified because ADUs may span physical records 
(i.e., @ record may start in the middle of an ADU). 


Direct Disk I/0 Opcodes 


I/O opcodes for direct I/O to disks (diskette opcodes ore described in 
porograph 6.19.3) do not have the some meonings as for other device 1/0. 
Those 1/0 opcodes that ore defined for the disk are defined below. All 
other opcodes ore ignored by the disk, as shown in table 6-2. 


6.19.2.1 
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Table 6-2, Direct Disk I/0 Opcodes 


Hexadecimal Opcode 1/0 Function I/O Action 
5, F Read Format : Returns disk ond track 
format. 
Write Format Formats a track. 
Read by ADU Inputs data starting in the 
specified ADU and sector. 
A Read by Track Inputs data starting in the 
specified track and sector. 
B Write by ADU Outputs data starting in the 
specified ADU and sector. 


C Write by Track Outputs data starting in the 
specified track and sector, 


E Store Register Returns the disk parameter 
registers, which are the same 
as the first three words of 
the read format data. 


Read Format codes 5,, and F 


The Read Format command requires specification of a buffer address in 
bytes 6 and 7 of the coll block and a track address in bytes 12 and 13. 
The specified buffer myst begin on a word boundary. The record length, 
character count, sectors per record, and sector number fields of the 
call block are ignored. Ten bytes of disk and track data are returned 
in the user buffer as shown in figure 6-2. 


USER 
GUFFER ce) WORDS/TRACK 
dIsK 
2 SECTORS /TRACK OVERHEAD/RECORD RELATED 


4 NO. HEADS (BITS 0-4) NO, CYCLINDERS (BITS S158) 


6 SECTORS/RECORD RECOROS TRACK 
TRACK 
e WORDS /RECORD RELATED 


Figure 6-2, Store Registers and Read Format Data 


6.19.2.2 


6.19.2.3 


6.19.2.4 


6.19.2.5 


6.19.2.6 


1630/SVC/SCI/0281/e 


6/27 


Write Format code 8 


The Write Format command requires specification of a physical record 
length in bytes 8 and 9 of the call block, and a track address in bytes 
12 and 13, The SCB buffer address, character count, and sector number 
fields are ignored. The addressed track is formatted to the given record 
length and the resulting number of sectors per record is returned in 
byte 14 of the call block. 


Store Registers |! code E 


The Store Registers commond tronsfers the disk parometers registers into 
the specified user buffer. The buffer address is specified in bytes 6 
and 7 of the call block and must begin on a word boundary. Bytes 8 
through 15 of the SCB are ignored. Six bytes of disk format data are 
returned in the buffer as shown in figure 6-2. 


Byte 0-9 are returned for read format opcodes (5 and Fis) and bytes 0-5 
ore returned for store register opcode (E,,). 


Read by ADU code 9 


The Read by ADU command transfers data from the disk to the specified 
buffer, The data buffer address is specified in bytes 6 and 7 of the SVC 
call block and must begin on a word boundary. The length of the physical 
record to be read is specified in bytes 8 and 9 and must be an even num- 
ber. The ADU number and sector offset from which to read the record are 
specified in bytes 12 through 15. The number of cheracters actually read 
is placed in bytes 10-11 by the system. 


Read by Trock (Opcode A 15) 


The Read by Track command transfer data from the disk to the specified 
buffer. The buffer address is specified in bytes 6 and 7 of the call 
block and must begin on a word boundary, The record length is specified 
in bytes 8 and 9, and must be an even number. The track address is spe- 
cified in bytes 12 and 13 and the sectors per record ond starting sector 
number ore specified in bytes 14 ond 15, The number of characters reod 
is returned in bytes 10-11. 


Write By ADU code B 


The Write by ADU command transfers data from a specified buffer to a 
specified address on disk, The buffer address is specified in bytes 6 
and 7 of the call block and must begin on a word boundary. The number 
of characters to write is specified in bytes 10 and 11 and must be an 
even number. The disk address to which the data is to be written is spe- 
cified by the ADU number and sector offset in bytes 12 through 15 of the 
coll block. If the character count is not an integral number of sectors, 
the remainder of that sector will be zeroed out. 


rece 
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6.19.2.7 Write by Track code C 


The Write by Track command transfers data from o specified buffer to a 
specified address on disk. The buffer address is specified in bytes 6 
and 7 of the call block and must begin on a word boundary. The number 
of characters to write is specified in bytes 10 and 11 and must be an 
even number, The disk address to which the data is to be written is spe- 
cified by the track address in bytes 12 and 13 and the sectors per re- 
cord and starting sector number in bytes 14 and 15, 


6.19.3 Direct Diskette I/0 


Some of the 1/0 opcodes for diskette operations, shown in table 6-3, 

are the some as for disk, although TAXO does not support diskette ad- 
dressing by ADU/sector offset. In addition, diskette I/0 allows some 
special functions, such as specifying logical track numbers and sector 
sizes. The following paragraphs describe the 1/0 operations for diskette 
which are supported by TAXO, 


0.19.3.1 Read Format codes 5), and F 


This command is exactly the same as for disk, except that a track address 
is required in bytes 12-13 of the 1/0 call block, Bytes 6-7 must contain 
the address of a 5-word buffer, which must begin on a word boundary, in 
which the system returns the some information as returned for disk 

(shown in figure 6-2). All other fields in the call block are ignore . 


Table 6-3. Diskette Direct Disk I/0 Opcodes 
Hexadecimal ‘Opcode 1/0 Function 1/0 Action 


0 Open Ignored (device type returned) 
1 Close Ignored 
2 Close EOF Ignored 
3 Open Rewind Ignored (device type returned) 
4 Close Unload Ignored 
5 Read Format Return disk/track fmt. 
6 Forward Space Ignored 
® 7 Back Space Ignored Formats Track 
; 8 Write Formot Formats Track 
2 9 Read ASCII Read data 
A Read Direct Read data 
B Write ASCII Write data 
Cc Write Direct Write data 
D Write EOF Ignored 
E Rewind Ignored 
é F Read. Format Return disk/track format 
10 Write Deleted Sector Writes delete code on sector 
11 


Read Deleted Sector Reads delete code on sector 


6.19.3,.2 Write Format code 8, 


This command requires q track address in bytes 12-13 of the call block, 
and o record length, given in bytes, in bytes 8-9, All other fields in 
the call block are ignored, TAXO formats the specified track, and returns 
the number of sectors per record in byte 14, 


6.19.3.3 


6.19.3.4 


6.19.3.5 


6.19.3.6 


6,.19.3.7 
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Read ASCII (Opcode 9,,), Read Direct (Opcode A 


These two commands transfer dato from the diskette to the user buffer 
whose address is specified in bytes 6-7 of the I/O call block. The 
length of the buffer is given in bytes 10-11, and must be an even num- 
ber, Bytes 12-13 specify the track from which the data is to be read, 
byte 14 is the number of sectors per record on that track (should be 1), 
and byte 15 is the sector number on the track at which the read operc- 
tion should begin. Under TAXO, there is no difference between the Read 
ASCII and Read Direct commands, The system returns the actual number of 
characters reod in bytes 10-11. 


Write ASCII code B, Write Direct code C 


These commands transfer data from the user buffer, pointed to by bytes 
6-7 of the call block, to the diskette. Bytes 12-15 contain the track/ 


‘sector address, as described in paragraph 6.19.3.3. Bytes 10-11 specify 
‘the number of characters to be written (must be an even number). TAXO 


makes no distinction between the Write ASCII and Write Direct commands. 


Write Deleted Sector code 10 


The diskette controller can “delete” a sector by writing a special data 
pattern on it. This operation can be performed by specifying a 10,, op- 
code (byte 2) and o track/sector address (bytes 12-15) in a normal 1/0 
call block, 


Read Deleted Sector code 11 


This operation is used to read the special data pattern written on a 
sector by the Write Deleted Sector operation. The Read Deleted Sector 
operation may be performed by specifying 11,, -opcode (byte 2) and a 
track/sector address (bytes 12-15) in a normal 1/0 call block. 


Special Diskette Options 


In addition to the operations described above, the diskette controller 
allows two options, variable sector lengths and logical track numbering. 


For any Read or Write operation, the user can specify the size of a sec- 
tor, in the range of 2 to 128 bytes. The sector length must be even, and 
is assumed to be 128 bytes unless otherwise specified, A smaller sector 
size for an 1/0 operation results in unused disk space (the difference 
between 128 and the specified sector size), To specify the sector length, 
bit 6 of the user flags (byte 5 of the call block) must be set to one 
and the desired sector size placed in byte 14 (normally used for sectors/ 
record). 


Logical trock numbering allows the user to assign an address to a track 
different from the physicol address of that track, This option enables 
the user to skip bad tracks in the track numbering. Logical numbers 
should still increase from zero as the head travels inwand on the dis-. 
kette, as do the normal addresses, Figure 6-3 shows a logically numbered 
disk. 
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O71) 2/3! PHYSICAL ADDRESS 


BAD TRACK 


Figure 6-3. Logical Track Addressing 


To assign a logical address to a track, a write format operation must be 
performed. Bit 6 of the user flags (byte 5) must be set to one, and the 
address to be assigned to the track must be in byte 14, 
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SCI_ COMMAND PROCESSORS AND SCI_INTERFACE ROUTINES 


General 


Command processors, in gerieral, can be any tasks that operate under TAXO, 
The following paragraphs describe the intended purpose of a command pro- 
cessor under SCI, as well as restrictions and a description of the S$ 
interface routines to be used by the processor to interface with SCI. 


Function And Usage 


Command processors are created to carry out some action requested by a 
command procedure. In some cases, the procedure is a trivial one, and 
serves only to bid o particular task (e.g., XGEN, XANAL, XCU). For many 
applications, such o procedure-processor relationship is all that is de- 
sired, In o more useful case, the procedure passes keyword parometer or 
synonym values to the processor, via the PARMS parometer of the .BID or 
-QBID, These values may be accessed by the processor by using the 
S$PARMS routine described in paragraph 7.3.2. 


Interface Routines 


Command processors communicate with the command interpreter fromework 
(i.e., access the terminal communication crea and parometers) by using 

a set of interface routines. Other routines are available to perform 
32-bit integer arithmetic operations, and to access the terminal local 
file, Command processors must be link edited with the routines, which are 
in the library .SCI.S$OBJECT on the system disk. A BLWP instruction is 
used to invoke a routine. 


There ore four major classes of interface routines: string utility sub- 
routines, SCI interface subroutines, arithmetic utility subroutines, and 
terminal local file access routines. 


String Utility Subroutines 


Operands for command processors are passed from SCI as character strings. 
These strings ore stored in buffers with the following form: 


STRING 
LENGTH 


where string length is the number of characters in the string (one byte 
per character), and the buffer is one byte longer thon the string. A maxi- 
mum of 256 can be specified as the string length. In the format illustra- 
tion, Cl, C2, and CN ore the characters in the string. 


Empty buffers reserved for string storage should have the buffer length 
minus one (maximum string length) in the first byte. The following rou- 
tines are provided to operate on strings. 
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S$IASC - Convert Binary Integer to ASCII. This routine is used to con- 
vert a 32-bit binary integer into an ASCII text string representing that 
number. Rl contains the address of the 32-bit number. R2 points to a 
buffer which is to receive the ASCII text. The buffer is of the form of 
the string variable, with the first byte containing the length of the 
buffer minus one. The 32-bit integer will either be taken as a two's 
complement number or a 32-bit positive binary number, depending on the 
base byte (second byte) of R3, If base is zero, the number is treated as 
a two's complement binary integer and will be converted into the ASCII 
representation of the decimal (base 10) number, with leading blanks and 
a “-" character if the number was negative. If base is anything but zero, 
the 32-bit integer is treated as positive, and will be converted into the 
ASCII representation of the integer in the specified base, with leading 
zeros. S$IASC puts the length of the ASCII string into the first byte 

of the receiving buffer. 


Calling Sequence: BLWP (a) S$IASC 


Registers Used: RO - error code returned by S$IASC 
Rl - address of the 32-bit integer 
R2 - address of the buffer which is to receive the 
ASCII text 
R3 byte 0: number of ASCII characters to be out- 
put (field width); zero means variable 
number; moximum is 32 
byte 1: Base (e.g., 10 or 16) into which the 
integer is to be converted, prior to 
representation in ASCII (O=decimal) 


Example: " 

INT DATA 2,0 INTEGER = 128K 

BUFFER BYTE 15 LENGTH OF BUFFER 
BSS 15 
LI R1I,INT R1 = ADDRESS OF INT 
LI R2,BUFFER R2 = ADDRESS OF BUFFER 

: LI R3,>0010 FIELD WIDTH = VARIABLE 

= BASE = 16 

BLWP @SSIASC CONVERT 


S$INT - Convert ASCII to Binary Integer, This routine will convert an 
ASCII text string which represents an integer EXPRESSION into a 32-bit 
binary value, The integer expression to be converted may contain the 
standard arithmetic operators +, -, *, and /, If the ASCII string con- 
tains numbers beginning with ">" or "0", the numbers ore assumed to be 
hexadecimal; otherwise it is assumed to be in the base specified in work- 
space register R3. 


Calling Sequence: BLWP @S$INT 


sean/eve/sci/onsi/e 
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Registers Used: RO - error code returned by routine 

R2 - pointer to the ASCII string to be converted 
to an integer 

R3 + pointer to a 4-byte (32-bit) buffer in which 
the converted binary integer is to be stored 

R4 - base of the number represented by the input 
string (e.g., 10 or 16). If R4 is zero, base 
10 is assumed. 


Example: : 

NUMBER BYTE 5 LENGTH OF TEXT 
TEXT ‘>AE80’ HEX NUMBER 
EVEN 

INT BSS 4 BUFFER FOR INTEGER 
Li R2,NUMBER R2 — ASCII] NUMBER 
LI R3,INT R3 = BUFFER 
ul R4,16 R4 = BASE 16 
BLWP @SSINT CONVERT THE NUMBER 


S$SCOM - Compare Two Strings. This routine compares two strings, and 
sets the arithmetic bits in the status register to reflect the results 
of the comparison. If one string is shorter than the other, it is as- 
sumed to be filled with NULL characters (00,,). If one string is a sub- 
string of the other (matching from the left), RO is set to zero, The 
two strings are pointed to by register "a" and "b", where "a" and "b" 
ore specified in the two bytes immediately following the call to S$SCOM 
(see example). 


Calling Sequence: BLWP @)S$SCOM 
Byte Ra, Rb 


Registers Used: RO - substring test code returned by S$SCOM: If 0, 
one string is a substring. If -1, the strings 
differ at some choracter. 

Ra - pointer to the first string 
Rb — pointer to the second string 


Example: 

FIRST BYTE 6 LENGTH OF FIRST STRING 
TEXT * SUBSTR’ 

SECOND BYTE 9 LENGTH OF SECOND STRING 
TEXT ‘ SUBSTRING’, 
Li R3.FIRST R3 POINTS TO FIRST 
LI RS,SECOND RS POINTS TO SECOND 
BLWP @S$SCOM COMPARE THE TWO 
BYTE = R3.R5 DEFINE ‘A* AND ‘B’ 
JEQ OUT THIS JUMP WILL NOT OCCUR 
MOV RO,RO 
JEQ SUB THIS JUMP WILL OCCUR 
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S$SCPY - Copy String. This copies the string pointed to by register "a" 
into the buffer pointed to by register "b", placing the length of the 
copy string in the first byte of "b". Registers "a" and "b" ore defined 
in the two bytes immediately following the coll to SSSCPY, as in SSSCOM, 
The buffer containing the string (pointed to by register "a") must not 
overlap the buffer in which the copy is te be placed (pointed to by re- 
gister "b"), The buffer at "b" must be set up as a string buffer, as 
described beginning of paragraph 7.3. If the length of the receiving 
buffer is less than the text string to be copied, an error code is re- 
turned in RO, If register "ao" is zero, or the string to be copied is 
the null string (zero length), the buffer length (first byte) of the 
buffer at "b” will be set to zero. 


Calling Sequence: BLWP (@ S$SCPY 
BYTE Ra, Rb 


Registers Used: RO - error code returned by S$SCPY 
: Ra - pointer to text to be copied 
Rb - pointer to buffer to receipt copy 


Example: 

STRING BYTE7 LENGTH OF STRING 
TEXT ‘COPY ME’ 

COPY BYTE 20 LENGTH OF BUFFER 
BSS 20 
LI R1,STRING R! = POINTER TO STRING 
LI R8,COPY R8 = POINTER TO BUFFER 
BLWP @SSSCPY CALL S$SCOPY 


BYTE  RI,R8 DEFINE ‘A’ AND ‘B’ 


SCI Interface Subroutines 


These routines are provided to allow a verb processor to access its 
parameters (PARMS and CODE keywords), locate and modify the synonym 
defined for the terminal, and return control to SCI, The task that uses 
this set of routines must be bid via .QBID or .BID. These routines may 
be used after a call to S$GTCA (Get Terminal Communications Area)ond 
prior to a call to S$RTCA (Release TCA). The terminal communications 
area acts as an information buffer between SCI and verb processors. The 
routine S$STOP (return control to SCI) may be called at any time. The 
maximum message length for the routine S$STOP is 77 charocters. 

S$GTA =- Get Terminal Communicetions Area. This routine is called to make 
the TCA available for use by the calling routine (a command processor). 
This routine must be called before a command processor may access key- 
word ond synonym values, ond get porometers passed to it by the SCI pro- 
cedure, | 


Calling Sequence: BLWP @)S$GTCA | 
Registers Used: RO - error code returned by S$GTCA 


Example: *BEGINNING OF COMMAND PROCESSOR 


BEGIN BLWP @SSGTCA OPEN TCA 
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S$PTCA - Put Terminal Communications Area. This routine should be called 
by a command processor which has written in the TCA (using the S$SETS 
routine), before the processor terminates or calls S$RTCA. 

Calling Sequence: BLWP @S$PTCA 

Registers Used: RO - error code returned by S$PTCA 


Example: 


*THE TCA HAS BEEN MODIFIED 
WRITE BLWP @ SSPTCA UPDATE THE TCA 


S$RTCA - Release Terminal Communications Area. This routine should be 
called by a command processor when it no longer needs access to the TCA 
(e.g., just before terminating). 


Calling Sequence: BLWP G@)S$RTCA 
Registers Used: RO - error code returned by S$RTCA 
Example: 


*THIS ROUTINE IS FINISHED WITH THE TCA 
BLWP @SSRTCA RELEASE. TCA 


S$NEW - Initialize the System Dato Base. This routine initializes a data 
base for use by the various system routines according to the terminal 
state, mode, and ID. Command processors which do not call S$GTCA (i.e., 
which need not access the terminal communications area), but which do use 
other S$XXX routines, must coll S$NEW before using any other S$XXX rov- 
tine. Processors which do call S$GTCA need not coll S§$NEW, since S$GTCA 


does so. 

Calling Sequence: BLWP @)S$NEW 

Registers Used: RO - error code returned by S$NEW 

Example: es em 


*THIS IS THE BEGINNING OF THE ROUTINE. 
BEGIN BLWP @S$NEW 


7/6 


S$PARM - Get the I-th Parometer. This routine may be used by a command 
processor to get the parometers in the TCA which were passed to it by 
the command procedure via the PARMS parameter of a .BID, .Q8ID, or 
-DBID primitive, These parometers are text strings, delimited by com- 
mas, as described in System Command Interpreter Manual under the .BID 
description, Register “a" contains an integer which is the number of 
the parometer desired. Register "b" points to a buffer, into which the 
text string is to be copied. The first byte of the buffer must contain 
the length of the buffer. If the buffer is too short, an error code is 
returned in RO, Registers "a" and "b" are specified in the two bytes 
immediately following the call to S$PARM, as in the S$SCOM routine. 

To find the values of keywords, use the S$SNCT (Search Name Correspon- 
dence Table) routine. 


Calling Sequence: BLWP @) S$PARM 
BYTE Ra, Rb 


Registers Used: RO - error code returned by S$PARM 
Ro - parameter number 
Rb - pointer to the buffer for the parameter 
text string , 


Example: 
PARMI BYTE 28 BUFFER FOR PARAMETER 
BSS 28 


ul R2,PARMI R2 = POINTER TO BUFFER 


LI R13 Ri = 3 (GET THE 3RD PARM) 
BLWP @S$PARM 
BYTE R1,.R2 DEFINE ‘A’ AND ‘B’ 

rs 


S$SETS - Set Synonym Value. This routine is used to define or redefine 

a synonym in the terminal communications area. The synonym is a text 
string, pointed to by register "a". The value to be assigned to the 
synonym is a text string pointed to by register “b", Registers "a" and 
"b" are defined in the same manner as in S$PARM. If register "b" is zero, 
or points to a zero length string, the synonym is deleted from the TCA, 


NOTE 
In order to update the TCA with the new synonym value, S$PTCA 
must be called after the last call to S$SETS, 


Calling Sequence: BLWP @S$SETS 
BYTE Ra, Rb 


Registers Used: RO - error code returned by S$SETS 
Ra - pointer to synonym nome text string 
Rb - pointer to synonym value text string 


1630/Svc/SC1/0281/e 


Example: 


7/7 


Example: 


3 


SYNO4. BYTE 5 _— LENGTH OF SYN04 NAME 
TEXT ‘SYNO4’ 
VALUE BYTE 15 LENGTH OF VALUE 


TEXT ‘DSO2.CAT1.INPUT’ 


LI 3,SYNO4 R3 = POINTER TO SYN NAME 
Ll _7,VALUE1 R7 = POINTER TO SYN VALUE 
SETS BLWP @SSSETS DEFINE SYN 


BYTE R3,R7_ ‘DEFINE ‘A’ AND ‘B’ 


S$MAPS ~ Map Synonym (Get its value). This routine will search in the 
terminal communications area for the synonym nome pointed to by Ra. If 
the synonym is found, and the buffer is large enough, its value will be 
placed in the buffer pointed to by Rb, with the length of the value 
string placed in the first byte of the buffer. The buffer is a text 
string buffer, with the first byte containing the length of the buffer 
minus one (i.e., the length of the text it will hold), as described in 
paregroph 7.3.1. If the buffer is too smoll, an error code will be re- 
turned in RO, If the synonym is not found in the TCA, a zero-length 
string is copied into the buffer. If the synonym name pointed to by Ra 
has a "," in it, the text preceding the "." will be replaced by its sy- 
nonym value, if any exists (similar to using quotes and the "a" in the 
SCI language). 


Calling Sequence: BLWP @S$MAPS 
BYTE Ra, Rb 


Registers Used: RO - error code returned by S$MAPS 
Ra - pointer to synonym name 
Rb - pointer to buffer for synonym valve 


ea ~ 


SYNOS BYTE 10 LENGTH OF SYNOS 
oe TEXT ‘SYNO4.DATA’ 
VALOS BYTE 50 LENGTH OF VALUE 
BSS 50 
Li 2.SYNO5 R2 = POINTER TO NAME 
Li 3, VALOS R3 = POINTER TO BUFFER 
MAPS BLWP @S$MAPS GET SYN VALUE 
BYTE R2,R3 
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S$SNCT - Search Nome Correspondence Toble. This routine is used to 

search the name correspondence table (which is the table in the ter- 
minal communications area containing synonyms ond key-words) for the 
synonym (if any) which is the immediate lexical (alphabetical) prede- 
cessor or successor of the text string pointed to by register Ra. Whether 
the predecessor or successor is found depends on the value in RO, If the 
desired synonym is found, its nome is placed in the Ra buffer and its 
value in the Rb buffer. If no synonym is found, a null string (zero 
length) is placed in the buffer pointed to be Ra. If Ra originally points 
to a zero length string, the lexically smallest synonym and its valve 

is returned, If Rb points to a zero length string, any synonym found 

will be returned in the Ra buffer, but its corresponding value is ig- 
nored. This routine is intended to be used to access synonyms in lexical 
order. Parameters entered by the PARMS parometer of a .BID, .QBID, or 
.DBID primitive are accessed using S$PARM (Get the Ith Parameter) routine. 


NOTE 

SSSNCT assumes that the Ra ond Rb buffers are 255 bytes long, and 
that the character count value in the first byte of each buffer 
is a count of the string currently in the buffer. This is the 
only S$ routine which does not check buffer length before writing 
in the buffer. 


Calling Sequence: BLWP G@)S$SNCT 


BYTE -Ra;:.. Rb 
Registers Used: RO - if 0, lexical successor will be searched for; 
if -1, lexical predecessor will be searched 
for 


Ra - pointer to buffer containing original string; 
synonym name, if found, will go here 

Rb - pointer to the buffer which receives the value 
of the synonym found, if any. 


Example: 


SYN BYTE 3 LENGTH OF SYN BUF 
NAME — TEXT ‘SYN° 

BSS 250 . 
VALUE BYTE 255 LENGTH OF VALUE BUF” 

BSS 255 . 

LI = ROO RO = GET SUCCESSOR 

Li = -R3.SYN - R3 = NAME OF SYN 

LI R4.VALUE R4 = VALUE BUFFER 
GETNXT BLWP @SSSNCT GET NEXT SYN 

BYTE R3,R4 DEFINE ‘A’ AND ‘B’ 

CLR RI RI =0 

MOVB *R3.R1 CHECK FOR 

JEQ OUT - FND OF NCT 


*PROCESS THE SYNONYM 


OUT 
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S$STAT ~ Get the Status of the Terminal. This routine returns the status 
of the terminal from which the calling routine (command processor) was 
activated, The information is returned as a 32-bit integer (two words), 
which have the following meaning: 


Ist byte: bit 0 is reserved 
bits 1-3 is the user privilege code, with this meaning, 
when set: 
bit 1 - management level (highest privilege) 
bit 2 - system level 
- bit 3 - is reserved for custom system use 
bits 4-7 is the current terminal mode, in the form of a 
hex number: 
O = batch mode or background 
1 = TTY mode 
F = VDT mode 


2nd byte: station ID 

3rd byte: reserved 

4th byte: the “CODE” value of the most recent 
, BID, .QBID, or .DBID 


Calling Sequence: BLWP G) S$STAT 


Registers Used: RO - error code returned by S$STAT 
R3 - pointer to a 32-bit buffer 


Example: 

EVEN 

INFO BSS 1 TERMINAL INFO 

ID BSS 1 STATION ID 
BSS 1 RESERVED 

CODE BS 1 ‘CODE’ 
LI R3, INFO R3 = POINTER TO BUFFER 
BLWP @SSSTAT GET STATUS 


S$SPLT - Split List into Components. This routine is used to remove the 
first element of o list, in the same manner os the .SPLIT primitive des- 
cribed in System Command Interpreter Monual. SSSPLT copies the first 
element (i.e., all text up to the first comma) of the list pointed to 

by RI into the buffer pointed to by R2, putting the rest of the list 
into the buffer pointed to by R3. RI and R3 may point to the same buffer. 


Calling Sequence: BLWP (@) S$SPLT 


Registers Used: RO - error code returned by S$SPLT 
R1 - pointer to list text string 
R2 - pointer to buffer to receive first element 
of the list 
R3 - pointer to buffer to receive the rest of the 
list 


7/10 
Example: 


LIST BYTE 33 LENGTH OF LIST 
TEXT ‘(20,LIST ACCESS’ 
TEXT ‘NAME,OUTPUT FILE)’ 


FIRST BYTE 20 LENGTH OF ‘FIRST’ BUF 
BSS 20 
ul R1,LIST RI = LIST POINTER 
LI R2,FIRST R2 = FIRST POINTER 
MOV RI1,R3 R3 = REST POINTER = R1 


BLWP @SS$SPLT 


S$STOP - Return to the System Command Interpreter. This routine is used 
to terminate a command processor, by returning control to SCI, and may 
be called any where within the command processor. If S$CLOS (see para. 
7.3.4) was colled earlier, with R1 = 0, the terminal local file will be 
displayed when control returns to SCI, If, upon calling S$STOP, R2 is 
not zero, the message text pointed to by R2 will be displayed after the 
terminal local file. In this way, command processors may return error 
or completion messages. The value of R] is converted to a five digit 
hexadecimal integer and assigned as the value of synonym S$CC. 


Calling Sequence: BLWP @)S$STOP 


Registers Used: R1 ~ completion code; if zero, then no error is 
indicated 
R2 - pointer to a text string; if zero, no message 
is displayed 
The value in R1 is converted to ASCII, base 16, and assigned to the syno- 


nym $CC if the processor was executed via ".BID", or the synonym $8C if 
the processor was executed via ".QBID". 


NOTE 
If this processor is started via .QBID from a batch SCI, both $CC 


and $8C are assigned the value in R1. 


Example: 
ERRO BYTE 18 MESSAGE LENGTH 
TEXT ‘NORMAL TERMINATION’ 
MOV @ERRCOD,R1 R1 = ERROR CODE 
INE  ERRET ; JUMP TO ERROR RETURN 
RETNRM LI R2,ERRO R2 = MESSAGE 
BLWP @SSSTOP RETURN TO SCI 
ERRET Ll R2,0 DON’T RETURN MESSAGE 


eral @SSSTOP RETURN ERROR CODE 


1630/svCc/SC1/0281/e 


7/11 


7.3.3 Arithmetic Utility Routines 


These four routines perform addition, multiplication, division, and 
subtraction using 32-bit signed integers as operands. Each routine 
also sets the status register bits 0-2, as do the normal assembly 
language arithmetic instructions. 


S$IADD - Add 32-bit Integers. This routine adds two 32-bit integers 
(two's complement numbers), yielding a 32-bit integer. The two operands 
are pointed to by R1 and R2, and the result is placed in the 32-bit 
buffer pointed to by R3, Any of the registers may point to the some 
32-bit area (e.g., add "A" to "A", giving "A"). The status register 
arithmetic bits are set, as in the normal assembly language A (add) 


instruction. 
Calling Sequence: BLWP @)S$IADD 
Registers Used: RO - error code returned by S$IADD (-1 means 
overflow) 
Rl - pointer to 32-bit integer 
R2 - pointer to 32-bit integer 
R3 - pointer to 32-bit buffer for result 
Example: 
NUM! DATA 1,0 FIRST NUMBER = 64K 
NUM2 DATA 0.FFFF SECOND NUMBER = 64K-1 
LI R1,NUMI R1] = NUMI POINTER 
LI R2.NUM2 R2 = NUM2 POINTER 
MOV R2.R3 R3 = RESULT POINTER 


BLWP «SsIADD ADD NUM1, NUM2, GIVING NUM2 


S$ISUB - Subtract 32-bit Integers. This routine is used to subtract 32- 
bit integers, and works similarly to S$IADD. If R1 is zero, the negative 
of the number pointed to by R2 is calculated. 


Calling Sequence: BLWP @) S$1SUB 


S$IMUL - Multiply 32-bit Integers. This routine multiplies the two 32- 
bit integers pointed to by R1 and R2, placing the result in the 32-bit i 
buffer addressed by R3. Any of the registers may address the same 32-bit 
area. This routine works the same as S$IADD and S$ISUB. 


Calling Sequence: BLWP @ S$IMUL 

S$IDIV - Divide 32-bit Integers. This routine divides the two 32-bit in- %, 
tegers pointed to by R1 and R2, placing the quotient in the 32-bit buffer = 
pointed to by R3 and the remainder in the 32-bit buffer addressed by R4, ie 
Any of the registers may address the some 32-bit area. If R3 = R4, only 


the quotient is stored. The status register arithmetic bits ore set, os. oe 
in S$IADD, : é 
Calling Sequence: BLWP @s$io1v 
Registers Used: RO - error code returned by ‘s$IDIV (divide ie zero=1) 


R1 - address of the dividend 
R2 - address of the divisor 
R3 - address of the quotient 
R4 - address of the remainder 


7.3.4 
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Exeomple: 
NUMBER DATA 8,0 NUMBER = 80000 
s 
Lt R1,NUMBER RI = NUMBER 
MOV RIR2 R2 = NUMBER 
MOV RLR3 R3 = NUMBER 
STWP R4 R4,R5 = REMAINDER 
Al R4,R4*2 
BLWP @SSIDIV DIVIDE 


* NUMBER = 1, R4 AND R5 =0 


Local Display File Routines 


The terminal local file of a terminal is a file of ASCII data to be dis- 
played. The following routines are provided for opening and closing 

such a file, and for constructing and writing records to the file. The 
task that uses this set of routines must be bid via .BID or .QBID. The 
record is assumed to be no more than 134 characters, Data items are 
written ot specific columns, and each line is terminated by a call to 
S$WEOL., Carriage control characters are edited into the text by the rou- 
tines as required, 


S$OPEN - Open the Terminal Local File. This routine opens the terminal 
local file or o user specified file for write access. The terminal local 
file should be used to display short messoges and listings to the termi- 
nal, If register R] is zero, the TLF is assumed, 


Calling Sequence: BLWP @)S$OPEN 


Registers Used: RO - error code returned by S$OPEN 
: Rl - zero or address of text containing the path- 
"name of a file 


Example: 
CLR RI R1 SET FOR TLF 
BLWP @SSOPEN OPEN TLF 


S$WRIT - Write to the terminal local file. This routine concatenates the 
text string addressed by R1 with the line currently being written to the 
TLF, If R2 is non-negative, it specifies the column (0..133) in which the 
text should begin. The text string is of the form described in poragraph 
7.3 with the first byte containing the length of the string. Additionally, 
if the byte value 7F,, is encountered in the string, then the preceding 
character is repeated n times, where n is the value in the byte follow- 
ing the 7F,, . The string should not contain device control characters, 
such as line feed, since these are supplied by S$WRIT os needed, 


Calling Sequence: BLWP @ S$WRIT 


Registers Used: RO - error code returned by S$WRIT 
R1 - address of text to be written 
R2 - column position at which text is to be placed 
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* ASSUME TPF AT SSWRIT HAS BEEN CALLED, AND 
* R2 POINTS TO THE END OF THE LAST WRITE 


NEWTXT BYTE 3 LENGTH OF NEW TEXT 
TEXT ‘* THIS TEXTIS A 
BYTE 7F STRING OF ASTERISKS 
REPEAT BYTE 0 REPEATED 
* THIS CODE WILL FILL THE 80 CHAR LINE WITH ASTERISKS 
LAB LI R3,80 CALCULATE NUMBER 
s R2,R3 OF ASTERISKS NEEDED 
SWPB R3 


MOVB R3,@REPEAT 
Ll RI,NEWTXT = R1 = ADDRESS OF NEWTXT 
BLWP @SSWRIT 


S$WEOL - Write End-of-line to the Terminal Local File. This routine ter- 
minates the current line being written to the TLF and writes it to the 
file. If S$WRIT has not been called since S$OPEN or S$WEQL, a blank line 
is written. 


Calling Sequence: BLWP @) S$WEOL 
Register Used: RO - error code returned by S$WEOL 


S$CLOS ~ Close the Terminal Locol File. This routine is used to terminate 
writing to the TLF, and should be called (if the TLF was opened) prior to 
a call to S$STOP. If R1 is zero, the file will be displayed after the 
command completes (before the S$STOP message is displayed). 


Calling Sequence: BLWP @ S$CLOS 


Registers Used: RO - error code returned by S$CLOS 
Rl - if zero, the terminal local file will be 
displayed; otherwise it will not. 


Example: 


SETO RI gee 
BLWP @SSCLOSE — CLOSE,DON'T DISPLAY 
or 


CLR RI 
BLWP @SSCLOS DISPLAY THE TLF 
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Table A-1, System Tosk IDs (S$PROGA) 


Code Name 

8) 

1 SMM 

2 SCILMT 
3 MLP 

4 SLMFOT 
5 TM$SBD 
6 TXSF 

7 DCOPY 
8 CPYSEQ 
9 PF$LIN 
A TM$DGN 
B FUTIL 
Cc 

D OQ$COPY 
E PATCHSYN 
F 

10 PF$LDE 
11 

12 TRCTSK 
13 PFSLMN 
14 SYSRST 
15 SVCKIL 
16 INSTAL 
17 SIS 

18 MADSAD 
19 - IDT 

1A CHKDSK 
1B RTSTSK 
1c MPISPI 
1D STS 

1E SLCMDP 
1F PF$LAS 
20 SCI990 
21 MRFSRF 
22 MAPDSC 
23 BRM 

24 QBID 
25 OQ$MGR 
26 BD 

27 RD 

28 CD 

29 DD 

2A SORTMG 
2B LLR 


_ Restore Directory 


Purpose 


Reserved 

Display Memory Map 

SCI Foreground Limitation Task 
Modify LUNO Protect 

Format System Log 

Scheduled Bid Task 

TX Set System File 

Disk to Disk Copy 

Copy Sequential Media 

Install Task 

Diognostic Task 

File Utility Task 

Reserved 

SCI Output Quever 

Patch Synonym Generator 
Reserved 

Delete Task 

Reserved 

Reserved 

Map Nome to ID/ID to Name 
System Restart Task 

Kill Task 

Instoll/Unload Disk Volume 
Show I/O Status 

Modify/Show Absolute Disk 
Initialize Date and Time as 
Check Disk Structures 

Remote Terminal Subsystem Download Task 
Map/Show Program Image 

Show Task Status 

Start Log Command Processor 

Assign Space on o Program File 
System Command Interpreter fy 
Modify/Show Relative to File - 
Map Disk 

SCI Background Resource Manager 
SCI Queve Bidder 

SCI Output Quever 

Bockup Director 


Copy Directory 
Delete Directory 
Sort/Merge 

List Logical Record 


Table A-1. 

Code Name 
2c CKS 

2D DES 

2E OCPRAL 
2F CONVRT 
30 TSOLNK 
31 MVI$ 
32 LD 

33 GEN990 
34 S$CCAF 
35 AT 

36 LSTSYN 
37 SVS 

38 FILMAP 
39 CPI 

3A TXMD 
3B TXFD 
x TXCP 
3D TXDX 
3E DXTX 
oF VC 

40 VB 

41 TBMUTL 
42 MKL 

43 ERRADD 
44 ITGS 
45 MMPACK 
46 ERRSHW 
47 SDBMS 
48 

49 DBMS 
4A GETLOG 
4B 

4C INVOL 
4D RWCRU 
4E LDC 

4F MDS 

50 MCCSCC 
51 TAMER 
52 SPL 

53 RCD 

FE ANALZ 
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System Task IDs (Continued) 


Purpose 


Copy KIF tq Sequential File 
DES (Sort/Merge) 

Release All LUNOs 

Convert 2.2 disk to 3.X disk 
Install System Overlay 
Modify Volume Information 
List Directory 

System Generation 
Copy/Concatenate and Append File 
Activate Suspended Task 
List Synonym 

Show Volume Status 

Map Program File 

Copy Program Image 

TX Map Disk 

TX Format Diskette 

TX Change Protection 

TX to DX Conversion 

DX to TX Conversion 

Verify Copy 

Verify Backup 

IBM Conversion Utility 
Modify Key Indexed File Logging 
Reserved 

Install Generated System 
Memory Packing 

Reserved 

Data Base Management System 
Reserved 

Data Base Management System 
Determine Log File to Use 
Reserved 

Install New Volume 
Read/Write From/To CRU Address 
List Device Configuration 
Modify Device Status 
Reserved 

Reserved 

Print File from Task 
Recover Disk 

Crash Dump Analyzer 


phe 
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SYSTEM PROCEDURE IDs 
Table A-2, Procedure IDs 


Hexadecimal 

Code Nome Purpose 

00 Reserved 

01 Reserved for System Task 

02 SCA System Communication Area 

03 SCI . System Command Interpreter 

04 BCA Background Communication Area 

05 Reserved 

06 Reserved 

07 Reserved 

10 RCOBOL COBOL Runtime (only to be used when COBOL 
has been installed on the system) 

11 Reserved 

50 Reserved 

51 Reserved 

8B Reserved 
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SYSTEM OVERLAY IDs 


Table A-4 provides a list of the System Task and Utility Overlay ID num 
bers in the system program file, Tqble A-3 provides a list of the SYSTEM 
OVERLAY ID numbers in the system overlay file. 


Toble A-3. System Overlay Numbers (.S$OVLYA) 


Code Name Purpose 

) OLNOO1 KIF B-Tree Split 

2 OLNOO2 KIF Insert 

3 OLNOO3 KIF Rewrite 

4 OLNOO4 KIF OPEN Random and Close 
5 OLNOO5 KIF3 

6 -OLNO06 KIF3 

7 OL.NOO7 KIF3 

8 OLNOOS KIF Delete Record Overlay 
9 OLNOO9 KIF Delete B-Tree Entry Overlay 
A OLNOOA KIF3 

B OLNOOB KIF3 

c OLNOOC KIF3 

D DMOVOD Disk Manager Overlay #1 

E DMOVOE Disk Manager Overlay #2 

F DMOVOF Disk Manager Overlay £3 

10 FMOV10 File Management Overlay #1 
11 FMOV11 File Management Overlay #2 
12 FMOV12 File Management Overlay #3 
13 FMOV13 File Management Overlay #44 
20 TM$OV1 TM$BID Error Recovery 


Toble A-4. System Task and Utility Overlay Numbers (.S$PROGA) 


Code Name Purpose 

0 Reserved 

2 PARSER System Command Interpreter PARSER 
3 E$EDIT Text Editor Edit Mode 

4 ESCMD$ Text Editor Command Mode 
5 INTACT System Generation 

6 BUILD System Generation 

7 L$$PB3 Debugger 

8 L$$PB4 Debugger 

9 L$$PB5 Debugger 

A L$$RS3 Debugger 


@ 
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Table A-4, System Task and Utility Overlay Numbers (.S$PROGA) 


(Continued) 
Code Name Purpose 
B L$$RS4 Debugger 
C DEBUG Debugger 
D L$$AB Debugger 
E L$$ASB Debugger 
F " L$$DEB Debugger 
10 L$$FB Debugger 
VW L$$mI Debugger 
12 L$$éMM Debugger 
13 L$$PB Debugger 
14 L$$RsS Debugger 
15 L$$PB1 Debugger 
16 L$$PB2 Debugger 
17 L$$RS1 Debugger 
18 L$$rS2 Debugger 
19 L$$DB Debugger 
1A L$$mMR Debugger 
1B IFROOT SCI SVC Processor Main Routine 
1c I$OSVC SCI SVC Processor SVC Section 
1D I$OUCB SCI SVC Processor UCB Section 
1E ISOERR SCI SVC Processor Errors 
1F L$$RS5 Debugger 
21 . DERROR System Commond Interpreter Errors 
22 MODSYN SCI Modify Synonym 
23 TINFO Terminal Information 
24 OUTQUE Output Quever 
25 MTMPMO SCI Modify Task/Overlay/Procedure Entry 
26 XSRTGEN Sort/Merge 
27 XTRANSL Sort/Merge 
28 XHEADER Sort/Merge 
29 XRECORD Sort/Merge 
2A XFIELD Sort/Merge 
2B XSORT Sort/Merge 
2c XSRTINT Sort/Merge 
2D XSRT Sort/Merge 
2E ». XLASPAS Sort/Merge 
2F XFILMGR Sort/Merge 
30 XMRGINT Sort/Merge : 
31 XMERGER Sort/Merge : 
40 SMS SCI Show Memory Status z 
50 L$$SPS Debugger 
51 L$$PB6 Debugger 
52 L$$APB Debugger 
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APPENDIX B 
DEVICE CHARACTER SET 


General 


TAXO supports ASCII 1/0 operations with all devices. This appendix 
consists of a keyboard code table, character tables for supported 


devices, listing the character sets for the devices, and the end-of- 
record and end-of-file sequences for the devices. 


B.2 Keyboard Code Transformations 


Table B-1 lists the keyboard generated code and the corresponding DSR 


- generated output code for Terminals supported by TAXO. Users who are 


nor getting the expected response from the keys being pressed should 
refer to the terminal instollation and operation hardware manual to . 
identify the proper keystroke to obtain the correct DSR output code. 


8.2.1 
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Key Toble 


Key labels in the softwore literature 
H 


1) Command CMD (HELP) 

2) Stop unlabeled key, orange (HOLD) 
3) Erase field 

4) TAB (Shift Skip) 

5) Skip 

6) Home 

7) Field Release Key (Return) | 

8) Erase Input 

9) Insert Line unlobeled key, gray 
10) Delete Character (DEL CHAR) 
11) Insert Character (INS CHAR) 
12) SEND (Enter) 


13) Left Field (BACK TAB) 


“ 14) Escape, ESC 


15) Up arrow 
16) Right arrow 
17) Left arrow 
18) Down arrow 


19) Repeat 


20) Fl - F8 (Event keys) 
+ Control 


21) CONTROL 


22) Backspace 


2 
= 
= 
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B.3 Video Display Terminals 
Table B-2 is the international set for the VDT ond Printer. 


RE CELE CECE LE 
s[7T Tet fot fet fel bel | 


Table B-2. Video Display Terminal and Printer Character Set 
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B.3.1 System Edit Keys 
System Edit Keys include cursor and display control keys including 
ERASE FIELD/DEL, LEFT ARROW, TAB, SKIP, HOME, RIGHT FIELD/RETURN, 
ERASE INPUT, DELETE CHAR, INSERT CHAR, RIGHT ARROW, ond RESET. These 
keys have special meanings for TAXO and entering the usually affects 
the display. Many of these keys are also task edit keys: the code for 
these keys is returned to the calling task for further processing. The 
Field Release Key also serves as an end-of-record for input. 


B.3.1.1 STOP Key 


The STOP key ({o)) implements a hold function as follows. Pressing the 
RESET key temporarily halts terminal output. Subsequent action depends 
on the next key entered: 


e If exclamation (!) is pressed, SCI is activated and the output 
@ continues. 
e If the CMD key is pressed, the current task is oborted. & 


e If any other key is pressed, the output resumes. 


B.3.2 


B.3.2.1 


B.3.2.2 


B.3.2.3 


B.3.2.4 


B.3.2.5 
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Task Edit Keys 
Task Edit Keys include TAB, DOWN ARROW, SKIP, HOME, RIGHT FIELD/RETURN, 
ERASE INPUT, CURSOR PAD (NSERT LINE), ENTER, LEFT FIELD, and UP ARROW. 


These keys generate codes returned to the calling task under the following 


conditions: 


e If no terminal input is in progress, or if standard device indepen- 
dent I/0 is in progress, no code is returned except that RIGHT 
FIELD/RETURN ond ENTER constitute end-of-record and end-of-file 
characters respectively, 


e If an extended input operation is in progress and if bit 5 of byte 
14 is set to one, these characters ore treated as event characters 
and are returned in byte 17 of the extended call. 


NOTE 

Several of the indicated keys are both task edit keys and system 
edit keys, The effects of the system and task edit keys are as ~ 
follows: 


ERASE FIELD [ce], @ 


This key fills the field with the fill character and positions the cur- 
sor at the beginning of the field, 


ERASE INPUT ey + [ea] 


This key acts the same os erase field but returns to the calling task 
with the character code 8E in byte 17 of the extended call block. 


Home [S] : 


This key positions the cursor at the beginning of the field and returns 
to the calling task with the character code 8C in byte 17 of the ex- 
tended call block. 


sk1pL_]+ [+] 


This key fills the field from the present cursor position to the end 
of the field with the fill character, places the cursor one character 
position beyond the field, and returns to the calling task with the 
character code 8B in byte 17 of the extended call block. 


a oe 


DELETE CHARACTER 


This key deletes the input character under the cursor, moves all cho- 
racters within the field to the right of the cursor left one character 
position, replaces the last character position of the field with the 
designated fill character, gnd leaves the cursor at its position prior 
to the keystroke, If there are no characters from the present cursor — 
position to the right end of the field, this key gives a warning beep, 
if the warning beep bit is set. 


a ae. ced 


B. 3.2.6 


B.3.2.7 


B.3.2.8 


B.3.2.9 


B.3.2.10 


a" 


B.3.2. 12 


B/6 
TAB [+] 


This key accepts all characters from the present cursor position to the 
first fill character (if other than.a blank) or to the end of the field, 
leaves the cursor one character position past the end of the field, 

and returns to the calling task with the character code 89 in byte 17 
of the extended call block. 


Insert Choracter + [o] 


If the character under the cursor is the fill character and not a blank, 
this key gives a warning beep and does nothing. Otherwise, it sets the 
input mode to insert characters, and gives a warning beep when on in- 
serted character causes characters to be lost on the right end of the 
field (if the warning beep bit is set), but lets the characters be lost 
off the end of the line if the warning beep bit is not set (any key- 
stroke not entering data will change the input mode back to the non- 
insert mode). 


Left Field [i] 


This key positions the cursor to the beginning of the field. If the 
cursor is at the beginning of the field, this key returns to the calling 
task with the character code 94 in byte 17 of the extended call block. 


Left Arrow (Le]) 


If the cursor is at the beginning of the field, this key gives a war- 
ning beep if the warning beep flog is set. Otherwise, it moves the cur- 
sor left one character position. ; 


Up_ Arrow ({t}) 


This key returns to the calling task with the character code 95 in byte 
17 of the extended call block. 


Right Arrow ([+]) 


This key leaves the character under the cursor intact, moves the cursor 
right one character position, and, if the cursor moves beyond the end 
of the field, returns to the calling task (if designated by the exten- 
ded call). This key gives a warning beep on keystrokes which would 
cause the cursor to move beyond the end of the field (if the warning 
beep flag is set). 


Down Arrow ([4]) , 


This key returns to the calling task with the character code 8A in byte 
17 of the extended call block. 


ae 
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B.3.2.13 SEND [S-] 
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B.3.3 


B.3.4 


Same as TAB, The return code in byte 17 of the extended call block is >93. 


Event Keys |®| fe] fe] [ol [e] fel (2) fo), Sl 


Several keys and key combinations are available on the VDT to signal 


special events to user application programs. These keys are otherwise 
not used by TAXO, 


STOP Ke 


The STOP key on the VDT provides a hold function as follows. Pressing 
the STOP key temporarily halts terminal output. Subsequent action de- 
pends on the next key entered: 


e If the exclamation point (!) is pressed, SCI is activated and output 
continues. 


If the CW key is pressed, the current task is aborted. 


e@ If any other key is pressed, the output resumes. 


B.3.5 End Of Record Key 


The end of record sequence for the VDT is the Field Release key. 


B.3.6 Character Types 


The key types for the VDT shown in table B-4 are indicated in the type 
column, The abbreviated characters CTRL denote using the control keys 
in conjunction with another key to generate the desired DSR output code. 
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Table B-4, VDT Character Code Transformations 


DSR 
: Output ; 
VDT Taste(n) Code Type* 
ERASE FIELD + = S 
CTRL ‘1° * 4) > 80 E 
CTRL + Fl x > 81 E 
CTRL + F2 + [o} > 82 E 
CTRL + F3 i > 83 E 
CTRL + FA ° > 84 E 
CTRL + F5 + > 85 E 
CTRL + F6 bi > 86 E 
LEFT ARROW [+] S sd 
TAB [=] > 89 ST 
DOWN ARROW [3] > 8A T 
SKIP [+] + (_] oder [wm] +[ ] > ST 
HOME ‘[s] > 8C ST 
FIELD RELEASE C4) > 8D ork 
ERASE INPUT + {el > 8E ST 
INSERT LINE +2 7eF 
DELETE CHAR Zz s 
INSERT CHAR + s 
RIGHT ARROW [3] s 
SEND (ENTER) [o-] > 93 Th 
LEFT FIELD [1] >94 T @ 
UecAnnon [+] >95 T 
CTRL + F7 : > 96 7 
CTRL + F8 : > 97 E 
COMMAND > 98 E 
PRINT ee? . 
CTRL '2 S A ia 
STOP = : ‘ 
CTRL '4! ‘ff - 3 
aoe ves + B) 90 E 
CTRL *6! > : ie . 
CTRL '7' +O dd 


* see next page . 
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CNTRL ‘3! 
ESC + [@] 
FI fo] ' 
F2 
F3 
F4 
F5 
F6 
F7 [2] 
F8 


* Type indicates one of the following: 


System Edit Character 
Task Edit Choracter 
End-of-file 


NH MWN 
wou 


> 8 
> 9B 
> 8] 
> 82 
> 83 
> 84 
> 85 
> 86 
> 96 
> 97 


axzm 
wow 


Aa 7 


7a BD DDB B® B® 


Event Choracter 
*"HOLD' Character 
End-of-record 
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B.4 Card Reader 


Table B-5 provides a hexadecimal to row punch conversion table, 
! 


Table B-5. Card Reader Character Set 


Row Row 
Hexadecimal Punches Hexadecimal Punches 
00 12.0-98-1 2F 0-1 
01 12-9-1 30 0 
0? 12.9-2 31 1 
03 12-9-3 32 2 
04 9.7 33 3 
05 0-9-8.5 34 4 
06 0-9-8-6 35 5 
07 0-9-8.7 36 6 
08 11-96 . : 
09 12.9.5 
OA 0-9-5 39 9 ; r 
0B 12.9-8-3 3A 8-2 
oc 12-9-8-4 3B 1184 
oD 12-9.8-5 3C 1284 
OE 12-9-8.6 3D 84 
OF 12.9-8.7 3E 08-46 
10 12-11-9-8-1 3F 0-8-7 
1 139-1 40 84 
12 11-9-2 41 12-1 
5 11-93 42 12-2 
14 "9-8-4 43 12.3 
15 9-8-5 44 12.4 
in 92 45 12-5 
17 0.96 46 a 
18 11-98 47 Se 
19 11.9.8-1 48 : 
cs 9.8.7 49 12-9 
1B 0-9-7 4A 11-t 
ic 1.9.8.4 4B ig 
ID A985 4c ‘ i . 
ete a 2 | 
IF 11-9.8-7 : 
20 None 4F 1146 @ 
2 128-7 50 11-7 
55 ne 51 118 
23 8-3 $2 11-9 
24 11-83 53 a; 
5 0-84 54 aa 
26 12 55 
a B.S 56 0S 
28 128-5 57 6 
29 118-5 58 es 
2A 118-4 59 a 
2B 128-6 SA 
3c 08.3 5B 128-2 
2D il 5C 08-2 


2E 128-3 =D nee 
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B.5 


Punches 


12-114 
12-11-7 
12-118 
12-11-9 
110-2 
110-3 
1104 
110-5 
1104 
110-7 
11.08 
110-9 
120 
12-11 
110 
110-1 


B/11 
Table B-5. Card Reader Character Set (Continued) 
Row Row 
Hexadecimal Punches, Hexadecimal 

SE 118-7 6F 
5F 0-8-5 10 
60 8-} 7 
ol 120-1 72 
62 120-2 73 
63 120-3 74 
64 120-4 rk} 
65 120-5 16 
66 12.04 77 
67 120-7 78 
68 120-8 79 
69 120-9 7A 
6A 12-111 7B 
6B 12-13-2 7c 
6c 32-11-3 7D 
6D 12-114 TE 
6E 12-11-5 1F 


Notes: 


12-9-7 


1, End of record occurs when the specified number of characters, or 


80 characters have been read, 


2. Maximum buffer size is 80 characters. 


End Of File Sequence 


The end-of-file sequence for the card reader is a slash (/) in column 


one and an asterisk (*) in column two. 


Line Printer 


TAXO provides support for various types of line printers. The characters 
which have special significance for the line printer are listed in 


table B-6 r) 
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APPENDIX C 
REENTRANT PROGRAMMING EXAMPLE IN ASSEMBLY LANGUAGE 


The following assembly li'stings show two task segments and two procedure 

segments, The task segments consist of data (some of it modifiable) while 
the procedure segments consist of pure code (executable code and constant 
data). 


These four segments (TASK1, TASK2, PROC], PROC2) were assembled using 
four separate assemblies (using the macro assembler SDSMAC). 
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TAS SNGHAC 947075 #€ 06:37:34 TUESDAY, AUG 02. 1977. 
PAGE 0001 
0001 INT = ’TASKI’ 
0003 : TASK HEADER 
$ 
0004 $ 
S23 oun area bct.9 or 
6002 0000 
0004 0000 
0007 DEF ALUNO. ALN, OPEN, OLNUM 
0008 DEF WRITES. UILNUM, WRITE2, U2LNUM 
0009 CEF CLOSE, ’ 1 RUNUM 
0010 $ 
OOM + ASSIGN LUND BLOCK 
0012 ¢ : 
0013 $006 EVEN 
0014 00 ALUND BYTE 0,0 10, STATUS 
0007 «00 
tole 008 0 ANUM BYTE >10 (iho Moreen 
0017 000A 0080 DATA 0,0,0,0,0.0 NOT USED 
0000 0000 
9000 
0010 0000 
0012 0000 
0014 0000 
0018 ot 40 ALUFLG BYTE >40.0 UTILITY FLAGS-GENERATE LUND 
0019 0018 0000 DATA 0,0,0,0.00,0.0.0 NOT USED 
O01A 0000 
Q0IC 9000 
OOLE 0000 
0020 0000 
0022 0000 
0024 0000 
0026 0000 
0028 0000 
0020 ¢ 
021 + OPEN PRE 
22 e 
0023 002A EVEN 
0024 002A «00 «(OPEN «BYTE 0,0 10, STATUS 
0025 Soe OO OPEN 
remy oo cnn BYE 6 _ LUND, TO BE FILLED IN 
027 ed - BYTE 0.0 SYSTEM, USER FLAGS 
0028 0030 00 BYTE 0,0 : DEVICE TVPE a 
0031 00 seni 
0029 0032 0000 DATA 0.0.0 
0034 0000 Se 
0036 0000 : 
0030 € 
31 + WRITE ONE PRB 
pee 0038 ‘ pad 
0034 heed oo WRITE! 0:0 10, STATUS 
35 003A (OB BYTE 3B WRITE ASCII 
0034 0038 00 WILNUM BYTE 0 LUND, TO BE FILLED IN 
0037 00% 00 BYTE 0.0 SYSTEN, USER FLAGS 
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TASK! SUSMAL 947075 sE 9 08:37:34 TUESDAY, AUG 02, 1977. 
PAGE 0002 
030 = . 
0038 003 0098" DATA TEXT! BUFFER ADDRESS 
OOF? 0040 0000 DATA TEXTIL CHAR COUNT 
0040 0042 N00D DATA TEXTIL CHAR COUNT 
0041 0044 0000 DATA 0 
0043 : WRITE TWO PRB 
e 
0044 e 
N45 0046 EVEN 
0046 oe 4 WRITE2 BYTE 0,0 10, STATUS 
0047 0048 OR BYTE 38 WITE ASCII 
0048 0049 «60 «WALNUM BYTE 0 LUNO, TO BE FILLED IN 
oo49 a 0 BYTE 6:0 SYSTEM. USER FLAGS 
0050 NOEL ODA’ DATA TEXT2 WUFFER ADDRESS 
0051 O04E N00 DATA TEXTA CHAR COUNT 
O52 0050 0000 DATA TEXT2L CHAR COUNT 
0082 0052 0000 DATA 0 
ou ’ 
QOes e ALASE PRA 
00% e 
0057 O09 Py 
ne 0056 «00 CLOSE 0,0 10, STATUS 
OOS? 0054 Ot BYTE *A CLOSE 
M40 OOF? «0 CLM BYTE 0 Lue. TO RE FILLED IN 
Ons one bs BYTE 0,0 YSTEH. USER FLAGS 
O42 OOEA 0000 DATA 0.0.0.0 WOT USED 
WEL A000 
WAR A000 
N06) 0000 
0063 ‘ 
nined ‘ RELEASE LUNG 
Qn45 * 
MSE O42 EVEN 
NAT pees ps4 RELEAS BYTE 0,0 10, STATUS 
0048 004 93 BYTE 393 RELEASE LUND 
O49 0045 00 RLM BYTE 0 : LUND, TO BE FILLED IN 
0070 ON4A 0000 DATA 0.0,0,0,0,0,0,0.0 NOT USED 
0068 O00) 
004A 0900 
ONAL 000 
OOLE 0000 
0070 0000 
0072 0000 
0074 0000 
0074 0000 
O71 e 
0072 « TASK 1 DATA 
0073 ¢ 
0074 0078 TS =-RSS. 442 
0078 On0@ 9 TEXT! TEXT ‘I AM TASK ONE’ 
0 =O 
WPA At . 
oop = 4D 3 
mer 20 
on 
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TASKI SOSMAC 947075 8E 08:37:34 THESDAY, AUG 02, 197. 
PAGE 0003 
OnE A 
OF 33 
00RD 48 
OOAL = 20 
OOA2 
QOA3 ME 
OOM 
0076 0000 TEXTIL EQ S-TENTI 
0077 OORS §«4€ =TEXT2 TEXT ‘NOM I Alt DONE’ 
OOK F 
oon? 5? 
ons 20 
oon a9 
CORA 20 
OOAB 4 
Oonc 4D 
OOAD 2 
ey 
OBO 
Bi 45 @ 
0078 000D TEXTA EQ! $-TEXT2 
0079 END 
§O ERRORS 
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TASK2 SNSMAC 947675 9€ 08:40:17 TUESDAY, AUG 02, 1977. 
PAGE 0001 
0001 IDT “TASK2’ 
0002 * 
0003 + TASK HEADER 
0004 + 
REF PROC! : 

0006 0000 0078’ DATA TWS,PROC1.0 _. TRANSFER VECTOR 

0002 0000 

0004 6000 
0007 DEF ALUNO, ALUM, OPEN, OLNUM 
0008 DEF WRITE! WILNUM, WRITE2,W2LNUM 
poised DEF (CLOSE, ) RELEAS, RLNUM 
ool! e ASSIGN LUNG BLOCK 
0012 * ‘ 
0013 0004 ae 
0014 eee . ALUND 0:0 10,STATUS 
0015 0008 = 91 BYTE 391 ALUNC OPCODE 
0016 0009 10 ALNUM BYTE 510 a LPO BIBER 
0017 000A 0000 DATA 0:0:0,0.0.0 USED 

OO0L 0000 

0010 000 

0012 0000 

0000 


3 

8 

3 

mR 
S828 E383 


g 
35 
333 


3 
s 
33288 


¢ 
« OPEN PRB 
¢ 
EVEN 
OPEN «BYTE 0.0 
BYTE 0 
CLM «AYTE 0 
BYTE 0,0 
BYTE 0.0 
DATA 0.0,0 
Sd 
+ WRITE ONE PRE 
# 
"EVEN 
WRITE BYTE 0.0 
BYTE >b 
WILNUM BYTE 0 
BYTE 0.0 


UTILITY FLAGS-GENERATE LUNO 


10,STATUS 

OPEN 

LUNG, TO BE FILLED IN 
SYSTEM, USER FLAGS 


DEVICE TYPE 


10, STATUS 


WRITE _ASCI! 
LUND. TO BE FILLED IN 
SYSTEM, USER FLAGS 


C/6é 


$ 


TASK2 SDSHAC 947075 #E 06:40°17 TUESDAY, AUG 02, 19/7. 
PAGE 0002 
003D =—00 
00% 0098’ TA TEXT! BUFFER ADORESS 
0039 0040 000D DATA TEXTIL CHAR COUNT 
0042 0000 DATA TEXTIL CHAR COUNT 
0041 0044 0000 DATA 0 
0042 ’ 
0043 * WRITE TWO PRB 
0044 ri 
0045 0046 EVEN 
0046 Heap bod WRITE2 BYTE 0.0 10, STATUS 
0047 0048 08 BYTE 5B WRITE ASCII 
0048 0049 «00 «~WOLMUM BYTE 0 LUNO, 10 8€ FILLED IN 
0049 eet M4 BYTE 0.0 SYSTEM, USER FLAGS 
0050 004C 00A5S’ DATA TEXT2 BUFFER ADDRESS 
0051 O04E 0010 DATA TEXTA CHAR COUNT 
0082 0050 0010 DATA TEXTA CHAR COUNT 
0053 0052 DATA 0 
OO + 
0055 * CLOSE PRE 
0056 + 
OOS7 0054 EVEN 
0058 0054 00 CLOSE BYTE 0,0 10, STATUS 
OS «00 
0059 0056 «(01 BYTE >! CLOSE 
Ho) 0057 00 CLM BYTE 0 LUNO, TO BE FILLED IN 
0061 nes . BYTE 0:0 SYSTEM, USER FLAGS 
1 
0042 005A 0000 DATA 0:0.0.0 NOT USED 
OSC 0000 
OO5E 0000 
0060 0000 
03 * 
O44 * RELEASE LUNO 
0045 e 
OO OOK2 EVEN 
0047 Nog on RELEAS BYTE 0:0 10, STATUS 
M4 9 BYTE 993 RELEASE LUNO 
0069 0045 00 RL BYTE 0 LUNO, TO BE FILLED IN 
6070 0044 0000 DATA 0,0:0.0,0,0.0:0.0 NOT USED 
0068 0000 
006A 0000 
WEC 0000 
QOOKE 0000 
0070 0000 
0072 0000 
0074 0000 
0076 6000 
0071 « 
0072 + TASK 2 DATA 
0073 € 
00748 0078 TWS BSS 16#2 
0075 0093 «49s TEXT! «TEXT “1 AM TASK THO’ 
009920 
OPA 4} 
oon «= 4D 
wre «20 
m9D 54 


G 
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TASKS 


0076 


0078 
w79 
NO ERRORS 
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SDSHAC 947075 #€ 08:40:17 TUESDAY, AUG 02, 1977. 


TEXTit EQU $-TEXTI 
JENT2 EXT ‘NOW I AM THROUGH’ 


4 
OO10 TEXT EQ $-TEXT2 
END 


3B ARYRLRSSU swe RR eeIeNSEs= 


PAGE 0003 
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APPENDIX_E 
KEY INDEXED FILE HASHED PLACEMENT SCHEME 


Key indexed files may be ‘created using the sequential placement scheme as 
described in Section 5, or may be created using a hashed placement scheme. 
Only one scheme is permitted per system, and a file can only be accessed 
by the type of system that created it. 


The hashed scheme uses the primary key of a logical record to calculate 
the physical record, or bucket, into which the record should be placed. 
If there is not enough room in the bucket for the logical record, it is 
ploced in a new, or overflow, bucket. A link is then made between the 
original and the new bucket. The number of possible hashed buckets is 
determined at file creation time. 


The hashed scheme uses more disk space than the sequential scheme, and 
the parometers used at file creation time have a much greater effect on 
the speed of operations performed on the file and the disk space con- 
sumed by the file. However, the hashed scheme may be more desirable thon 
the sequential placement scheme because of how the Read by Primary Key 
operation functions when hashing is used. 


The Read by Primary Key takes advantage of the hashing algorithm and by- 
passes most of the searching involved in finding the bucket which con- 
tains the desired logical record, However, this advantage is somewhat 
diminished if there are many overflow buckets linked to the hashed bucket. 


The structure of a Read by Primary Key (43,, opcode) operation is the 
some as that of a Read by Key (42,, opcode) operation; except that the 
primary key is used and the currency function will not allow a subse- 
quent use of a Read Next or Read Previous operation except in the case 
of duplicate keys. If a Read Next or Read Previous is issued, and there 
are no more duplicates, a B5 informative code is returned in byte 0 of 
the currency block. 


If a Read by Primary Key operation is applied to a sequentially formatted 
key indexed file, it functions as if it were a Read by Key operation. 


1630/svc/sc1/o281 /e 


F/1 


APPENDIX F 


STANDARD DEVICE NAMES 


The following list defines the standard TAXO device name format. 


Device Name 
Disk DSxx 
Interactive Terminals STxx 
Magnetic Tape MT xx 
Card Readers CRxx 
Line Printers LPxx 
Communications CMxx 
NOTES 


The letters "xx" represent a two-digit number assigned by SYSGEN, 
Values are sequential within device type and cre in the range 01 
through 99, 
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TASK STATE CODES 
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Several supervisor calls return a task state code in byte 1 of the super- 
Visor call block, The STS as well as several debug commands list the 
stote codes of tasks. The codes are defined in table G-1. 


Table G-1. 
Code 


Task State Codes 


(Hexadecimal) Significance 


Active task 

Active task 

Terminated task 

Task in time delay 

Suspended task 

Currently executing task 

Task awaiting completion of 1/0 

Task awaiting assignment of a device for 1/0 
Task awaiting disk file utility services 

Task awaiting file management services 

Task awaiting overlay loader services 

Task awaiting initial load 

Task awaiting disk management services 

Task awaiting tape management services 

Task awaiting system overlay loader services 
Task awaiting task driven supervisor call processor 
Task awaiting Get Memory services 

Task suspended for co-routine activation 

Task awaiting terminotion task services 

Task awaiting completion of ony 1/0 

Task awaiting memory manogement services 

Task is eligible for roll-out when requested I/0 completes 
Task activated while roll is in progress 
Suspended for initiative I/0 threshold 
Suspended for locked directory 

Suspended for task monagement directory buffer 
Task suspended for queve input 

Dummy task state — 
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APPENDIX H 
SVC_CODES 


3 


General 


Table H-1 contains a list of the codes associated with the calls used 
in TAXO, 


Table H-1. SVC Codes : 
Call Block 


Hexadecimal - Length (Bytes) 

Call Code Decimal 

1/0 Calls 
Perform 1/0 Operation 00 12 
Wait for 1/0 =)! 4 
Wait for Multiple ‘initiate 1/0's 36 4 
Get Event Character x” 4 
Abort 1/0 OF 1 
Get Event Charocter by LUNO” 39 4 
File Utility Request 15 24 

Program Control Calls 
Execute Task 2B 12 
Activate Suspended Task 07 3 
Scheduled Bid Task . 1F 14 
Load an Overlay : 14 7 
End of Task 04 _ 
End of Program 16 1 
Time Delay 02 4 
Change Priority We 2 
Poll Status of Task in Terminel 
Task Set | 35 8 
Unconditional Wait 06 1 
Activate Time Delay Task . OE 3 
Get Parometers 17 6 
Self Identification “QE 6 
End Action Status 2F 10 
Reset End Action 3E 6 
Map Program Name to ID ; 31 16 
Bid Task 05 8 
Do NOT Suspend 09 2 

Memory Control Calls 
Get Memory 12 4 
Release Memory 13 4 
Get Common Data Address 10 2 

1 


Return Common Data Address 1B 


ec 
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TASK? SDSHAC 947075 #E 08:40:17 TUESDAY, AUG 02, 1977. 
PAGE 0003 
00% at 
OF 53 
000) aR 
oat 20 
0on2 54 
00357 
00M af 
0078 000D TEXTIL EQU. $-TEXT! 
OO77 OOS 4E TEXT2 TEXT “NOW I AM THROUGH’ 
00ns AF : ; 
QOA? 5 
OOM 20 
On? 49 
OMA 20 
QOAR at 
OOAC aD 
ond 
COME SA 
OOF a8 
00m) 52 
oor! aF 
One? 55 
oon? 47 
ORs 48 
007e 0010 TEXT. QU $-TEXT? 
m7 END 
NO ERRORS 
on 
ar. = Cel 
Z : 


0013 9000” 
00614 0000 D620 
0002 0000 
0015 0004 DB00 
0006 0000 
0016 0006 DBOC 
OOOA 0000 
0017 OOOC DBOO 
GOCE 0000 
0018 0010 DeO0O 
0012 9000 
0019 0034 DB00 


xe 


* 
* 
* 


PROC1 


C/8 


13813852 MONDAY, JAN 23, 1976. 


PROCEDURE SEGMENT 1 

IDT “PROC1° 

DEF PROCI 

REF PROC2 

REF ALUNO. ALNUM, OPEN: OLNUM 

REF WRITE1.W1LNUM.WRITE2, W2LNUM 
REF CLOSE. CLNUM, RELEAS. RLNUM 


PROCEDURE ONE 


nove GALNUM. RO MOVE LUNO NUMBER TO PRB’S @ 
MOVB RO, @OLNUM 

MOVB RO. @WILNUM 

MOVB RO. @W2LNUM 

MOVB RO. @CLNUM 

MOVB RO, @RLNUM 


XOP @OPEN, 15 OFEN LUNO 
XOP @WRITEL.15 WRITE TEXT 1 
Bs @PROCZ GO TO PROC 2 
END 
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PROC? SDSMAC 947075 aE 08:43:22 TUESDAY, AUG 02, 1977. 
. , PAGE 0001 
0001 t 
0002 a PROCEDURE SEGMENT 2 
0003 a 
0004 IDT ‘PROC?’ 
0005 DEF PROC? 
0064 : REF WRITE2, CLOSE, RELEAS 
0008 P| PROCEDURE. Tu 
0009 r 
0 , Eu 8 
0011 0000 2FEO XOP @WRITE2,15 WRITE TEXT 2 
0002 0000 
0012 0004 FEO XOP @CLOSE,!5 CLOSE LUND _ 
3 XOP @RELEAS.15 RELEASE LUNO #eDUMMY IF NOT FILES? 
0014 0008 2FEO XOP @£0T, 15 END OF TA6X 
G00A 
0015 ry 
001 ‘ CONSTANT DATA oe Se 
0018 000C 08 EDT BYTE 4.0 END OF TASK 
0000 00 
0019 2 
wo 
: » AUG 02, 1977. 
SOSMAC 947075 8 06:43:25 TUESDAY, AUG 02 nie esi 
0020 0000 
ND ERRORS 
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The following link editor listing documents two link editor executions: 
The first link editor execution links task segment 1 and procedure seg- 
ments 1 and 2, The second link editor execution links task segment 2 
| with procedure segments 1 and 2. Thus TASK! (task segment 1 and proce- 
| dure segments 1 and 2) shares procedures 1 and 2 with TASK2, 


SDGLNK 936060 V2 08/02/77 09321127 PME 1 
COMMAND LIST 
FORMAT —«- SWAGE 


TASK TASK! 
DEMO, OBJECT. TASKI 
SOSLNK 736060 V2 08/02/77 09221:27 PAE 2 
LINK WP 


CONTROL. FILE = . DEMO. LAKCNTRL. TASK! 
LINKED OUTPUT FILE = .DEMO.PROG 
LIST FILE = .DEMO.LIST.LINKI 
NUMBER OF OUTPUT RECORDS © 3 
QUTPUT FORMAT = IMAGE 


SUSLNK 936060 V2 08/02/77 09521127 PME 3 


PROCEDURE 1, PROCt © ORIGIN = 0000 LENGTH = 0024 (PROCEDURE 1D = 1) 


MOLE ND ORIGIN LENGTH «TYPE DATE «TIME. «CREATOR 
®& proct fang ane IE IRD Seealiae 


DEFINITIONS 
WE VALUE NO) ONAME,SsCVALUE NO. VALUE NOE: VALUE ND 
PROC! 0000 1 
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t 
TI 990/10 SOSLNK 936060 V2 08/02/77 09:21:27 PRE 4 


PROCEDURE 2, PROC2 ORIGIN = 0040 LENGTH = 000E (PROCEDURE ID = 2) 
MODULE NO ORIGIN LENGTH = TYRE DATE TIME CREATOR 


PROC2 3 0040 QO0E INQUDE = «08/02/77 = 0B: 
4 OO4E 0000 INCLUDE = 0B/02/77 OB 4H 


DEFINITIONS 
WE jVALEND NA «(VALLE NO OE «(VALLE 6ONWE OVALE NO 
PROC2 «0040 3 


Ti 990/10 SDSLNK 936060 V2 08/02/77 09:21:27 PAE OS 


PHASE 0. TASK! ORIGIN = 0060 LENGTH = 00B2 (TASK ID = t) 


MOTULE =60-NO)OCORIGIN, «= LENGTH TYPE DATE TIME CREATOR 
TASK! 5 0060 0082 INCLUDE 06/02/77 06:37:34 = SDSMAC 


DEFINITIONS 


WE 80 VALUE MEAL NDsNAMESsCVALUE Ns AECL 
ANIM 60069 5) #ALUND «(0085 5 CMM 0087 3 CLOSE OOB4 5 
OLMm 0080 5 OPEN 000A 5 ARELEAS 0002 5 RM OOS 5 
WILNUM 009B 5 WAM OOAF S| WRITE! 0098 5 WRITE2 O006 $ 


#00¢ LINING COMPLETED 
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e 


TI 990/10 SOSLNK 936060 V2 06/02/77 09:24:21 PAE 
COMMAND LIST 


TI 990/10 SDSLNK 936060 V2 06/02/77 09:24:21 PAGE «2 
LINK PP @ 


CONTROL FILE = . DEMD.LUKCNTRL. TASK2 
LINKED OUTPUT FILE = .OD.PROG 
LIST FILE = .BEMD.LIST.LINK2 
NUMBER OF OUTPUT RECORDS = 1 
OUTPUT FORMAT = IMAGE 


TI 990/10 SDSLNK 936060 V2 08/02/77 09:24:21 PME 3 


PROCEDURE 1. PROC] ORIGIN = 0000 LENGTH = 0024, DUMMY (PROCEDURE ID = 1) 


MODULE ==NO ORIGIN, LENGTH TYPE DATE TIME CREATOR 


PROC 0000 0024 NCLUDE 08/02/77 08:41:22 «= SDSMAC 
} 0024 0000 NCLUOE 08/02/77 0B241826 «= SUSMAC 


DEFINITIONS , @ 


HAE = VALUE NOsONAME-SsCVALUE ND NAEsCALUE ND NAME“ NO. 
PROCI 0000 1 
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’ 
TI 990/10 SUSLIG! 936060 V2 08/02/77 09226221 PAGE § 


PROCEDURE 2, PROC2 ORIGIN = 0040 LENGTH = QOOE. DUMMY (PROCEDURE ID = 2) 


MODULE 6M «(ORIGIN = LENGTH TYE DATE TIME CREATOR 


PROC2 3 (00d0 OO0E INCLUDE 08/02/77 «= 08:43:22» SPSMAC 
: SOSMAC 


4 = OE 0000 INCLUDE 08/02/77 = 08243225 


DEFINITIONS 
WHE VALUED 6OMAE «(VALUED ORAMECOVALUE NDEs: NO 
PROC2 0040 3 


TL 990/10 SDSUK 936060 V2 08/02/77 09:24:21 PROE 5 


PHASE 0, TASK2 ORIGIN = 0060 LENGTH = 0086 (TASK ID = 2) 


MODULE NO ORIGIN LENGTH TYPE DATE TIME CREATOR 
TASK2 5 0060 0085 INCLUDE 08/02/77 08:40:17 SDSHAC 


DEFINITIONS 


WHE «VALUE ELE sNAEs VALUE ND ECL 
ALNUM 60069 5S BALUND «(0066 5 CLNUM 60087 «5 CLOSE + 00B4 5 
OLN 0080 5 OPEN 008A 5  ARELEAS 002 3 RLM OOS § 
WILNUM 0098 5 W2LNUM 009 5 WRITE! 0098 $ WRITE2 O00R0 5 


att LINKING COMPLETED 


C/14 


The following listing is a map of the program file used in the previous 
link edit runs. 


FILE MAP OF .UEN0. PROG 
TODAY IS 09:27:09 TUESDAY, AUG 02, 1977. 

TASKS: 

oY TASK Ua? O00 ro NANYN omy OL /Y se ra 1 0 

02 TASK? See eee 04 «NOR ay Bh Boia O: 0: 0 

3 

1D WANE LENGTH LOAD RES 0D INSTALL DATE 

Ot PROC! 0024 0000 nN oR 8/ 2/26 9 Ot 0: 

02 000E 0040 WON 8/ 2/26 (03 0 

OVERLAYS: 

1D =NAME LENGTH LOAD weed OMY INSTALL DATE 
@ The following listings are sample outputs from TASK2 and TASK, respec- 
tively. 


1 AM TASK TWONOW 1 AM THROUGH 


T AM TASK ONENOW I AM DONE 


e 
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APPENDIX D 


GLOBAL _LUNOs 
Table D-1 provides a list of the Global LUNO assignments. 


Table D-1, Global LUNO Assignments 


D3 


(D4-FF 


Assignment 


System Console (STO1) 

Foreground TCA File S$FGTCA 
Background TCA File S$BGTCA 

TCA Library File S$TCALIB 
***Reserved 

***Reserved 

***Reserved 

News File 

***Reserved 

System Disk 

S$OVLYA-Overlay File (System LUNO) 
S$PROGA-Program File (System LUNO) 
***Reserved 

S$PROGA-Progrom File(System LUNO) 
S$ROLLA-Roll File (System LUNO) 
S$PROGA-Program File System (System LUNO) 
S$SDS$-Program File (System LUNO) 
***Reserved/WI*** ; 
System Log File S$SLG1 

System Log File S$SLG2 

System Log Device 

System Log Attention Device 
***Reserved 

Pascal Program File 

***Reserved 

Disk 2 

Disk 3 

Reserved for System Assignment 
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APPENDIX _E 


KEY INDEXED FILE HASHED PLACEMENT SCHEME 


Key indexed files may be ‘created using the sequential placement scheme as 
described in Section 5, or may be created using a hashed placement scheme, 
Only one scheme is permitted per system, and a file can only be accessed 
by the type of system that created it. 


The hashed scheme uses the primary key of a logical record to calculate 
the physical record, or bucket, into which the record should be placed. 
If there is not enough room in the bucket for the logical record, it is 
placed in a new, or overflow, bucket. A link is then made between the 
original and the new bucket. The number of possible hashed buckets is 
determined at file creation time, 


The hashed scheme uses more disk space than the sequential scheme, and 
the parameters used at file creation time have a much greater effect on 
the speed of operctions performed on the file and the disk space con- 
sumed by the file. However, the hashed scheme may be more desirable than 
the sequential placement scheme because of how the Read by Primary Key 
operation functions when hashing is used. 


The Read by Primary Key takes advantage of the hashing algorithm and by- 
posses most of the searching involved in finding the bucket which con- 
tains the desired logicol record. However, this advantage is somewhat 
diminished if there are many overflow buckets linked to the hashed bucket. 


The structure of a Read by Primary Key (43,, opcode) operation is the 
some as that of a Read by Key (42,, opcode) operation; except that the 
primary key is used and the currency function will not allow a subse- 
quent use of a Read Next or Read Previous operation except in the case 
of duplicate keys. If a Read Next or Read Previous is issued, and there 
are no more duplicotes, o B5 informative code is returned in byte 0 of 
the currency block. 


If a Read by Primary Key operation is applied to a sequentially formatted 
key indexed file, it functions as if it were a Read by Key operation. 
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APPENDIX F 


STANDARD DEVICE NAMES 


The following list defines the standard TAXO device name format. 


Device Nome 
Disk DSxx 
Interactive Terminals STxx 
Magnetic Tape MT xx 
Card Readers CRxx 
Line Printers LPxx 
Communications Chix 
NOTES 


The letters "xx" represent a two-digit number assigned by SYSGEN, 
Valves are sequential within device type and are in the range 01 
through 99. 


G/1 
APPENDIX G 


TASK STATE CODES 


Several supervisor calls return a task state code in byte 1 of the super- 
Visor call block, The STS as well as several debug commands list the 
state codes of tasks. The codes are defined in toble G-1. 


Toble G-1. Task State Codes 


Code 
(Hexadecimal) Significance 
00 Active task 
01 Active task 
04 Terminated task 
05 Task in time delay 
06 Suspended task 

@ 07 Currently executing task 
09 Task awaiting completion of 1/0 
OA Task awaiting assignment of a device for I/0 
OB Task awaiting disk file utility services 
00 Task awaiting file management services 
OE Task awaiting overlay loader services 
OF Task awaiting initial load 
11 Task awaiting disk management services 
12 Task awaiting tape manogement services 
13 Task awaiting system overlay loader services 

: 14 Task awaiting task driven supervisor call processor 
- 15 Task awaiting Get Memory services 

17 Task suspended for co-rouvtine activation 
18 Task awaiting termination task services 
19 Task awaiting completion of any 1/0 
1A Task awaiting memory management services 
1B Task is eligible for roll-out when requested 1/0 completes 
1c a Task activated while roll is in progress 

a 1D Suspended for initiative I/0 threshold 

* 1E ; Suspended for locked directory 

1F Suspended for task monagement directory buffer 
24 Task suspended for queve input 
FF Dummy task state ~ 
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APPENDIX H 


SVC CODES 
“sy 
General 


Table H-1 contains a list of the codes associated with the calls used 
in TAXO, 


Table H-1. SVC Codes a 
Call Block 


Hexodecimal - Length (Bytes) 

Call x Code Decimal 

1/0 Calls 
Perform 1/0 Operation 00 ae 12 
Wait for 1/0 mm) 4 
Wait for Multiple ‘Initiate 1/0's 36 4 
Get Event Charocter 30 4 
Abort 1/0 OF 1 
Get Event Character by LUNO 39 4 
File Utility Request 15 24 

Program Control Colls 
Execute Task 2B 12 
Activate Suspended Task = 07 3 
Scheduled Bid Task F 4 
Load an Overlay ; 14 7 
End of Task , 04 » 1 
End of Program 1% 4 1 
Time Delay 02 4 
Change Priority W. - 2 
Poll Status of Task in Terminel 
Task Set | 35 8 
Unconditional Wait 06 1 
Activate Time Delay Task OE 3 
Get Parometers 17 6 
Self Identification “QE 6 
End Action Status 2F 10 
Reset End Action 3E 6 
Map Program Name to ID 3 31 16 
Bid Task 05 8 
Do NOT Suspend 09 2 

Memory Control Calls 
Get Memory 12 4 
Release Memory 13 4 
Get Common Data Address 10 2 

1 


Return Common Data Address 1B 


F H/2 
Table H-1, SVC Codes (Continued) 


{ 
i 
j 


Call Block 
Hexadecimal Length (Bytes) 
Call Code Decimal 
; Miscellaneous Calls 

Getdata 1D : 12 
Putdata 1c 12 
Convert Binary to Decimal OA 8 
Convert Decimal to Binary 0B 8 
Convert Binary to Hexadecimal | oc 6 
Convert Hexadecimal to Binary - 6 

Date and Time 03 4 
System Log 21 7 
Retrieve System Information 3F  - 

Privileged Superyiecr Calls 

Install Task r 25 ~ 20 
Install Procedure : 26 16 - 
Install Overlay 27 1B 
Delete Task 28 6 
Delete Procedure 29 6 
Delete Overlay 2A 6 

Kill Task 33 8 
Suspend Awaiting Queve Toput 24 ey aN 
Read/Write TSB 2c JO. 
Read/Write Task 2D .!) 

Get System Pointer Table higceis 32 a) z 
Initialize Date and Time 3B :) 4 
: Disk Manager 22 Ae 4 
Assign Space On Program File 87 6. 
Initialize New Volume 38. ‘ «8 
Install Disk Volume . 20 18 
Unload Disk Volume 34 18 
Direct Disk 1/0 00 12 

awe ; 


Alle Rechte, sowie Anderungen und Verbesserungen behalten wir uns 
ohne Anktindigung vor. 


All rights reserved, including the right to make alterations and improve- 
ments without previous notice. 


Nous nous réservons tous les droits ainsi que l’application de toute 
modification ou amélioration, sans avis préliminaire. 


Nos reservamos todos los derechos asi como hacer modificaciones y 
mejoras sin previo aviso. 


Ci riserviamo tutti diritti, come pure modifiche e correzioni senza pre — 
avviso. 
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